Connect GitLab Self-Managed

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.

Before you start

Not sure where a value comes from? See 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.
- Paradime must reach your GitLab over https. If your instance is behind a firewall, allow the Paradime IP addresses.

Step 1: Open the GitLab Self-Managed integration

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

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.

Install for me (recommended)
Use my own bot

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.

In GitLab, sign in as an instance administrator and create a personal access token with the api scope.
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.
Under Bot role, pick Developer or Maintainer. See Bot role.
Under Projects, select the projects that Paradime installs on.
Click Install.

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

Sign in with GitLab works on gitlab.com only. On GitLab Self-Managed, use an administrator token.

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. On GitLab 17.9 or later, 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 data/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 4.With this method, an administrator registers the OAuth application by hand. See Step 5.

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.

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:

In GitLab, open Admin area > Applications > New application (see GitLab’s guide). The link on the card opens this page.
Name the application Paradime.
Paste the Redirect URL that Paradime shows.
Select Trusted, so people are not asked to authorize Paradime. Keep Confidential selected.
Select the api, read_user, and write_repository scopes, then save.
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.

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.

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://<your GitLab>/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. 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.
Bot role	Developer or Maintainer.	Not from GitLab. It is the role Paradime gives its `paradime` service account on each project. See 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.
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 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.
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 and Configure GitLab as an OAuth 2.0 provider.

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

Troubleshooting

Message	What to do
`'<url>' is not an https GitLab URL`	Enter the instance URL with `https://`. Paradime does not connect over `http`.
`GitLab <version> is not supported: 16.0 or later`	Upgrade GitLab to 16.0 or later.
`<user> 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 <n> 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 <project> (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.

​Before you start

​Step 1: Open the GitLab Self-Managed integration

​Step 2: Enter your instance

​Step 3: Choose how Paradime gets in

​Step 4: Check the install

​Step 5: Register the OAuth application

​Change the sign-in URL

​Where to find each value

​Troubleshooting

Before you start

Step 1: Open the GitLab Self-Managed integration

Step 2: Enter your instance

Step 3: Choose how Paradime gets in

Step 4: Check the install

Step 5: Register the OAuth application

Change the sign-in URL

Where to find each value

Troubleshooting