> ## Documentation Index > Fetch the complete documentation index at: https://docs.paradime.io/llms.txt > Use this file to discover all available pages before exploring further. # Connect GitLab Self-Managed > Install the Paradime GitLab connection on your own GitLab instance, with an administrator token or your own bot, a private CA certificate, a separate sign-in URL, and the OAuth application. This page shows how to connect projects on your own GitLab instance (GitLab Self-Managed, for example an enterprise install) to Paradime. For projects on gitlab.com, see [Connect gitlab.com](https://docs.paradime.io/integrations/gitlab/gitlab-com.md). ## Before you start Not sure where a value comes from? See [Where to find each value](#where-to-find-each-value). * **GitLab version:** GitLab **16.0 or later**, reachable over `https`. Token rotation needs GitLab 17.9 or later. A blocking DinoAI reviewer sets the merge request reviewer state on GitLab 19.3 or later. * **In GitLab:** for **Install for me**, you need a GitLab **instance administrator**. For **Use my own bot**, you need a token for a bot that is a member of the projects. * **In Paradime:** you have permission to edit the workspace's Git repository settings. * **GitLab tier:** **Install for me** creates an instance service account. Service accounts need GitLab Premium or Ultimate. If your instance does not allow them, use **Use my own bot**. * **Network:** * GitLab must reach the Paradime webhook host, for example `api.us.paradime.io` in the US region. See [Network requirements](https://docs.paradime.io/integrations/gitlab#network-requirements). * Paradime must reach your GitLab over `https`. If your instance is behind a firewall, allow the [Paradime IP addresses](https://docs.paradime.io/developers/ip-restrictions.md). ## Step 1: Open the GitLab Self-Managed integration 1. In Paradime, go to **Settings > Integrations**. 2. On the **Workspace** tab, find **GitLab Self-Managed** and click **Connect**. You can also connect when you create a workspace. In the repository step, choose **GitLab Self-Managed**. ## Step 2: Enter your instance Under **GitLab instance**, fill in the fields: | Field | Required | What to enter | | - | - | - | | **Instance URL** | Yes | The `https` address of your GitLab, for example `https://gitlab.example.com`. Paradime uses this address for every API call, clone, and webhook check. A gitlab.com address is refused here: use the **GitLab** integration for gitlab.com. | | **Sign-in URL (if your users reach GitLab at a different address)** | No | The address that people's browsers open to link their GitLab account, for example `https://gitlab.internal.example.com`. Use it when your network gives GitLab one address for servers and another for people. Paradime keeps using the instance URL for everything else. | Then, under **CA certificate (PEM)**, add a certificate if your GitLab's TLS certificate is signed by a private CA. Paste the PEM chain, or upload a `.pem`, `.crt`, or `.cer` file. Each certificate starts with `-----BEGIN CERTIFICATE-----`. Leave it empty if your certificate comes from a public CA. > [!NOTE] > > Paradime uses the CA certificate for every call to your GitLab, and keeps it after a reinstall or a reconnect. Paradime never shows the certificate again. Paste only certificates: Paradime refuses a private key. ## Step 3: Choose how Paradime gets in Under **How Paradime gets in**, pick one method. > [tab] Install for me (recommended) > > Paradime creates its own instance service account named `paradime`, adds it to your projects, and creates the webhooks. Paradime also registers its OAuth application on your instance, so people can link their GitLab account. > > 1. In GitLab, sign in as an instance administrator and create a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with the `api` scope. > 2. In Paradime, paste it into **Instance admin personal access token** and click **Find projects**. Paradime shows the GitLab version and the user it signed in as. > 3. Under **Bot role**, pick **Developer** or **Maintainer**. See [Bot role](https://docs.paradime.io/integrations/gitlab/gitlab-com.md#bot-role). > 4. Under **Projects**, select the projects that Paradime installs on. > 5. Click **Install**. > > Paradime uses the token once and does not store it. You can revoke it in GitLab when the install is complete. > > > [!NOTE] > > > > **Sign in with GitLab** works on gitlab.com only. On GitLab Self-Managed, use an administrator token. > [tab] Use my own bot > > Use a bot user, a group access token, or a project access token that you manage. Paradime stores the token in Vault and does not show it again. > > 1. In GitLab, create a token for the bot with the `api` and `write_repository` scopes. On GitLab 17.9 or later, add the `self_rotate` scope too, so Paradime can [rotate the token](https://docs.paradime.io/integrations/gitlab/connection-health.md#token-rotation) before it expires. > 2. Make sure the bot is a member of each project, with the **Developer** role or higher. > 3. In Paradime, paste the token into **Bot personal access token**. > 4. Under **Projects**, enter the project paths, one per line, for example `data/analytics/dbt-core`. > 5. Click **Connect**. > > If the bot cannot manage webhooks, Paradime gives you a URL and a secret token for each project. You add the webhooks yourself in Step 4. > > With this method, an administrator registers the OAuth application by hand. See [Step 5](#step-5-register-the-oauth-application). ## Step 4: Check the install When the install is complete, Paradime shows a checklist under **GitLab is connected**: the GitLab version, the bot user, the token expiry date, the webhook on each project, and how many workspaces Paradime linked. Paradime links every workspace that already clones one of the projects, also with a deploy key. Turbo CI, on-merge runs, Lineage Diff, and DinoAI Code Review then work on those workspaces. If a project shows **Add the hook in GitLab with the URL and secret below**, add the webhook yourself. The steps are the same as on gitlab.com. See [Add a webhook yourself](https://docs.paradime.io/integrations/gitlab/gitlab-com.md#add-a-webhook-yourself). ## Step 5: Register the OAuth application People link their GitLab account through an OAuth application on your instance, so git in the Code IDE runs as them. **Install for me** registers the application for you. If the registration failed, or you used **Use my own bot**, the GitLab integration page shows **Register the Paradime OAuth application**. An instance administrator does this once: 1. In GitLab, open **Admin area > Applications > New application** (see [GitLab's guide](https://docs.gitlab.com/integration/oauth_provider/)). The link on the card opens this page. 2. Name the application `Paradime`. 3. Paste the **Redirect URL** that Paradime shows. 4. Select **Trusted**, so people are not asked to authorize Paradime. Keep **Confidential** selected. 5. Select the `api`, `read_user`, and `write_repository` scopes, then save. 6. In Paradime, paste the **Application ID** and the **Secret**, then click **Save**. Paradime stores the secret in Vault. When the application is saved, people can link their account. See [Link your GitLab account](https://docs.paradime.io/integrations/gitlab/connect-a-repository.md#link-your-gitlab-account). > [!TIP] > > The application that **Install for me** registers is not marked **Trusted**, so people see a GitLab authorization page the first time they link. To skip that page, an administrator can edit the `Paradime` application in GitLab and select **Trusted**. ## Change the sign-in URL To add, change, or remove the sign-in URL after the install, open the GitLab Self-Managed integration page. On the connection card, click **Edit** next to **Sign-in URL**. An empty value means **Same as instance**. ## Where to find each value Each field in the install wizard, what to enter, and where to get it in GitLab. | Field in Paradime | What to enter | Where to get it in GitLab | | - | - | - | | **Instance URL** | The `https` address your servers use for GitLab, for example `https://gitlab.example.com`. | The address in your browser when you open GitLab, without a path. To check the version (16.0 or later), open `https:///help`. | | **Sign-in URL** (optional) | The address people's browsers use, when it differs from the instance URL. | Ask your GitLab administrator. Leave it empty when everyone uses the instance URL. | | **CA certificate, optional** | The PEM chain of the private CA that signed your GitLab's TLS certificate, or a `.pem` or `.crt` file. | Ask the team that runs your GitLab. On a Linux package install, the certificates are set up under `/etc/gitlab/ssl`. See [Configure SSL for a Linux package installation](https://docs.gitlab.com/omnibus/settings/ssl/). Leave it empty for a public CA. | | **Instance admin personal access token** | A personal access token with the `api` scope, from an instance administrator. | As an administrator: avatar > **Edit profile** > **Access tokens** > **Add new token**. Select the `api` scope and a short expiry date. Paradime uses it once and does not store it. See [Personal access tokens](https://docs.gitlab.com/user/profile/personal_access_tokens/). | | **Bot role** | **Developer** or **Maintainer**. | Not from GitLab. It is the role Paradime gives its `paradime` service account on each project. See [Bot role](https://docs.paradime.io/integrations/gitlab/gitlab-com.md#bot-role). | | **Projects Paradime installs on** / **Project paths, one per line** | Each project's full path, for example `data/analytics/dbt-core`. | The part of the project URL after your GitLab address. It is also on the project's **Settings > General** page. See [Manage projects](https://docs.gitlab.com/user/project/working_with_projects/). | | **Bot personal access token** (Use my own bot) | A token with the `api` and `write_repository` scopes. On GitLab 17.9 or later, add `self_rotate`. | Create it as the bot user, or create a [group access token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) or [project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/). The bot needs the **Developer** role or higher on each project. See [Personal access tokens](https://docs.gitlab.com/user/profile/personal_access_tokens/). | | **URL** and **Secret token** (webhook) | Paste both into a new webhook in GitLab. | The project's **Settings > Webhooks** > **Add new webhook**. Select **Merge request events** and **Comments**. See [Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/). | | **Redirect URL**, **Application ID**, **Secret** (OAuth application) | Copy the Redirect URL into GitLab, then paste the Application ID and Secret back into Paradime. | **Admin area > Applications > Add new application**, as an instance administrator. See [Step 5](#step-5-register-the-oauth-application) and [Configure GitLab as an OAuth 2.0 provider](https://docs.gitlab.com/integration/oauth_provider/). | **Install for me** creates an instance service account. Service accounts need GitLab Premium or Ultimate. See [Service accounts](https://docs.gitlab.com/user/profile/service_accounts/). ## Troubleshooting | Message | What to do | | - | - | | `'' is not an https GitLab URL` | Enter the instance URL with `https://`. Paradime does not connect over `http`. | | `GitLab is not supported: 16.0 or later` | Upgrade GitLab to 16.0 or later. | | ` is not an administrator of this GitLab instance` | Create the token as an instance administrator, or use **Use my own bot**. | | `Sign in with GitLab installs on gitlab.com only: use an owner token on self-managed GitLab` | Paste an administrator token instead. | | `The owner token needs the api scope` | Create the administrator token again with the `api` scope. | | `The CA bundle must be PEM certificates only (-----BEGIN CERTIFICATE----- blocks)` | Paste only `CERTIFICATE` blocks. Remove private keys and other text. | | `Certificate of the CA bundle is not a valid PEM certificate` | Copy that certificate again from your CA. | | `GitLab refused to create the Paradime service account (403): connect with a bot token instead` | Your instance does not allow service accounts. Use **Use my own bot**. | | `GitLab refused hook management on (403): the hook needs a project Maintainer` | Add the webhook yourself, or pick the **Maintainer** bot role. | | `GitLab rejected the token` | The token is wrong, expired, or revoked. Create a new one. | | A TLS or certificate error when Paradime calls GitLab | Your GitLab uses a private CA. Add the CA certificate in Step 2 and install again. | ## Related topics - [GitLab](https://docs.paradime.io/integrations/gitlab/index.md) - [Connect gitlab.com](https://docs.paradime.io/integrations/gitlab/gitlab-com.md) - [GitLab connection health](https://docs.paradime.io/integrations/gitlab/connection-health.md) - [Connect a GitLab repository](https://docs.paradime.io/integrations/gitlab/connect-a-repository.md) - [Importing a repository](https://docs.paradime.io/products/settings/git-repositories/importing-a-repository/index.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.