Connect GitLab with a personal access token

In situations where you are not an admin of your GitLab repository, or otherwise do not have the necessary permissions to authenticate your GitLab account with LinearB via Oauth, you can still connect by using GitLab personal access tokens.

Create a personal access token in GitLab

GitLab describes how to create a personal access token within your GitLab user account. Click here to learn how to create a personal access token in GitLab

Set your Expiration Date

It's advisable to set an expiration date long into the future, or if possible set no expiration date. If a GitLab token expires, there is a potential for data inconsistencies in the gap of time between when the token expires and a new token is added. In these instances please contact support@linearb.io to assist in validating and correcting any data issues.

Grant the correct permissions

The personal access token will need the following options selected:

• read_user
• api
• read_repository
• write_repository

What if I don't/can't grant write_repository permissions?

The only write permission LinearB asks for is on webhooks. LinearB uses this to connect a webhook to your repo and gather data into the LinearB app in real-time. This permission can be excluded from your token if your organization has security restrictions, however, data collected by LinearB will only update every 2 hours. This can cause confusion in reviewing metrics, and also will cause long delays in WorkerB notifications for time-sensitive matters such as PR review requests.

An alternative to using the token-level authentication is to create a service account in your GitLab org, with admin permissions to all relevant repos. Typically a "global admins" group is already created in GitLab instances Learn more about creating groups in GitLab here. This service account can be connected to LinearB using Oauth.

Add your GitLab token to LinearB

Once generated, paste your personal access token into LinearB's connect page. If you have not yet connected a Git account, you will be directed to this page upon logging in. If you have already connected a GitLab account, click on the gear icon in the top right of your page, select Company Settings, click on the Git tab, and click the Add Integration button. Paste in your token and LinearB will begin processing your GitLab data!

Reauthorize your GitLab token with LinearB

To reauthorize an expired GitLab token, please generate a new token using the instructions above, go to Company Settings -> Git and click on the three dots next to your existing GitLab token connection. Select reauthorize Git and add your new Token ID.

If you have any additional questions don't hesitate to reach out to us via email. You can also chat about anything Git or dev related if you join our Dev Interrupted Discord server!