> ## 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.com > Install the Paradime GitLab connection on a gitlab.com top-level group with Sign in with GitLab, an Owner token, or your own bot token. This page shows how to connect projects on **gitlab.com** to Paradime. For your own GitLab instance, see [Connect GitLab Self-Managed](https://docs.paradime.io/integrations/gitlab/self-managed.md). ## Before you start Not sure where a value comes from? See [Where to find each value](#where-to-find-each-value). * **In GitLab:** you are an **Owner** of the top-level group that holds your dbt™ projects. To use **Use my own bot** instead, 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 a GitLab [service account](https://docs.gitlab.com/user/profile/service_accounts/). Service accounts need GitLab Premium or Ultimate. On the Free tier, use **Use my own bot**. * **Network:** if your network limits outbound traffic from GitLab, allow the webhook host. See [Network requirements](https://docs.paradime.io/integrations/gitlab#network-requirements). ## Step 1: Open the GitLab integration 1. In Paradime, go to **Settings > Integrations**. 2. On the **Workspace** tab, find **GitLab** and click **Connect**. You can also connect GitLab when you create a workspace. In the repository step, choose **GitLab**. The same install steps open there. ## Step 2: Choose how Paradime gets in Under **How Paradime gets in**, pick one method. > [tab] Install for me (recommended) > > Paradime creates its own GitLab service account named `paradime` in your top-level group. It adds the account to your projects and creates the webhooks. You give Paradime access once, and Paradime does not store it. > > You can give access with **Sign in with GitLab** or with an Owner token. > > **With Sign in with GitLab** > > 1. Under **Owner token**, click **Sign in with GitLab**. > 2. Under **Bot role**, pick **Developer** or **Maintainer**. See [Bot role](#bot-role). > 3. Under **Projects**, enter the project paths, one per line, for example `analytics/dbt-core`. All projects must be in the same top-level group. > 4. Click **Sign in with GitLab** at the top of the card. > 5. On gitlab.com, sign in as an Owner of the top-level group and authorize Paradime. > > GitLab sends you back to the GitLab integration page. Paradime uses the sign-in once to create the service account and the webhooks, then revokes it. > > **With an Owner token** > > 1. In GitLab, create a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with the `api` scope, as an Owner of the top-level group. > 2. In Paradime, paste it into **Owner 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](#bot-role). > 4. Under **Projects**, select the projects that Paradime installs on. All projects must be in the same top-level group. > 5. Click **Install**. > > Paradime uses the token once and does not store it. You can revoke it in GitLab when the install is complete. > [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. 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 `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 3. ### Bot role The bot role is the role that the `paradime` service account gets on each project. | Role | What it lets Paradime do | | - | - | | **Developer** | Post commit statuses and merge request notes, and push branches. If GitLab disables a webhook, a project Maintainer re-enables it in GitLab, or you repair it with an Owner token. | | **Maintainer** | Everything a Developer can do. Paradime also re-enables and re-creates webhooks that GitLab disabled, without asking you. | ## Step 3: Check the install When the install is complete, Paradime shows a checklist under **GitLab is connected**: * The GitLab version. * The bot user, for example `@paradime`. * The token expiry date, and how many days are left. * The webhook on each project. * 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. You do not have to switch them to HTTPS. To clone over HTTPS too, see [Connect a repository](https://docs.paradime.io/integrations/gitlab/connect-a-repository.md). ### Add a webhook yourself If a project shows **Add the hook in GitLab with the URL and secret below**, the bot could not create the webhook. Add it yourself. > [!WARNING] > > Copy each secret token before you close the checklist. Paradime keeps only a hash of it and cannot show it again. 1. Click **Open webhooks in GitLab**, or open the project's **Settings > Webhooks** in GitLab. 2. Add a webhook with the **URL** and **Secret token** from Paradime. 3. Select the trigger events that Paradime lists for the project: **Merge request events** and **Comments**. 4. Save the webhook. 5. In Paradime, click **I've added the hooks**. If you lose a secret, click **Re-install hooks** on the connection card to get a new one. See [Connection health](https://docs.paradime.io/integrations/gitlab/connection-health.md#re-install-the-webhooks). ## More than one top-level group On gitlab.com, each GitLab connection covers one top-level group. To connect projects in another group: 1. On the GitLab integration page, click **Install on another top-level group**. 2. Run the install again for that group. Each group gets its own connection card. ## Link your GitLab account On gitlab.com, people link their GitLab account through Paradime's own OAuth application. You do not register an application. Each person links their account once, so their Code IDE commits and pushes are their own. See [Link your GitLab account](https://docs.paradime.io/integrations/gitlab/connect-a-repository.md#link-your-gitlab-account). ## 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 | | - | - | - | | **Sign in with GitLab** | Nothing. You sign in to gitlab.com in a new window. | Sign in as a user with the **Owner** role on the top-level group. Check your role in the group's **Manage > Members** page. See [Roles and permissions](https://docs.gitlab.com/user/permissions/). | | **Owner personal access token** | A personal access token with the `api` scope, from an Owner of the top-level group. | 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](#bot-role). | | **Project paths, one per line** / **Projects Paradime installs on** | Each project's full path, for example `analytics/data/dbt-core`. | The part of the project URL after `gitlab.com/`. It is also on the project's **Settings > General** page. All projects must be in one top-level group. 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. Add `self_rotate` so Paradime can rotate it. | Create it as the bot user (avatar > **Edit profile** > **Access tokens**), 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/). | **Install for me** creates a GitLab 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 Owner of any top-level group` | Sign in, or create the token, as an Owner of the top-level group. A Maintainer is not enough. | | ` is not an Owner of ` | The user is an Owner of another group. Use an Owner of the group that holds the projects. | | `Install one top-level group at a time: run the install again for the next group` | Select projects from one top-level group only. Then use **Install on another top-level group** for the others. | | `The owner token needs the api scope` | Create the Owner token again with the `api` scope. | | `GitLab refused to create the Paradime service account (403): connect with a bot token instead` | Your GitLab tier or group settings do not allow service accounts. Use **Use my own bot**. | | `GitLab refused hook management on (403): the hook needs a project Maintainer` | The bot cannot manage webhooks. 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. | ## Related topics - [Connect GitLab to Paradime: gitlab.com and GitLab Self-Managed](https://docs.paradime.io/changelog/2026-11-04/gitlab-integration.md) - [Connect GitLab Self-Managed](https://docs.paradime.io/integrations/gitlab/self-managed.md) - [GitLab](https://docs.paradime.io/integrations/gitlab/index.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) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.