Connect gitlab.com

This page shows how to connect projects on gitlab.com to Paradime. For your own GitLab instance, see Connect GitLab Self-Managed.

Before you start

Not sure where a value comes from? See 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. 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.

Step 1: Open the GitLab integration

In Paradime, go to Settings > Integrations.
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.

Install for me (recommended)
Use my own bot

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

Under Owner token, click Sign in with GitLab.
Under Bot role, pick Developer or Maintainer. See Bot role.
Under Projects, enter the project paths, one per line, for example analytics/dbt-core. All projects must be in the same top-level group.
Click Sign in with GitLab at the top of the card.
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

In GitLab, create a personal access token with the api scope, as an Owner of the top-level group.
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.
Under Bot role, pick Developer or Maintainer. See Bot role.
Under Projects, select the projects that Paradime installs on. All projects must be in the same top-level group.
Click Install.

Paradime uses the token once and does not store it. You can revoke it in GitLab when the install is complete.

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.

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 before it expires.
Make sure the bot is a member of each project, with the Developer role or higher.
In Paradime, paste the token into Bot personal access token.
Under Projects, enter the project paths, one per line, for example analytics/dbt-core.
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.

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.

Copy each secret token before you close the checklist. Paradime keeps only a hash of it and cannot show it again.

Click Open webhooks in GitLab, or open the project’s Settings > Webhooks in GitLab.
Add a webhook with the URL and Secret token from Paradime.
Select the trigger events that Paradime lists for the project: Merge request events and Comments.
Save the webhook.
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.

More than one top-level group

On gitlab.com, each GitLab connection covers one top-level group. To connect projects in another group:

On the GitLab integration page, click Install on another top-level group.
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.

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.
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.
Bot role	Developer or Maintainer.	Not from GitLab. It is the role Paradime gives its `paradime` service account on each project. See 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.
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 or project access token. The bot needs the Developer role or higher on each project. See 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.

Install for me creates a GitLab service account. Service accounts need GitLab Premium or Ultimate. See Service accounts.

Troubleshooting

Message	What to do
`<user> 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.
`<user> is not an Owner of <group>`	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 <project> (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.

​Before you start

​Step 1: Open the GitLab integration

​Step 2: Choose how Paradime gets in

​Bot role

​Step 3: Check the install

​Add a webhook yourself

​More than one top-level group

​Link your GitLab account

​Where to find each value

​Troubleshooting

Before you start

Step 1: Open the GitLab integration

Step 2: Choose how Paradime gets in

Bot role

Step 3: Check the install

Add a webhook yourself

More than one top-level group

Link your GitLab account

Where to find each value

Troubleshooting