Skip to main content
Table of Contents

Connecting GitLab to LinearB

Connect GitLab to LinearB using a Personal Access Token (PAT) to sync repositories, merge requests, and Git activity.

Steven Silverstone
Updated by Steven Silverstone

If you do not have administrative access to your GitLab repository or lack the required permissions to authenticate GitLab with LinearB via OAuth, you can still connect using a GitLab Personal Access Token (PAT).

To generate a PAT that grants LinearB the required access, you must be an organization owner or have Maintainer or Owner permissions for the relevant repositories.

Follow the steps below to generate your token and connect GitLab to LinearB.

Summary

What this guide covers

  • Generating a GitLab Personal Access Token (PAT)
  • Selecting the required scopes (permissions)
  • Connecting GitLab to LinearB using the PAT
  • Reauthorizing the PAT in LinearB (expired token)
  • Troubleshooting common issues

Before you begin

  • GitLab account with Maintainer or Owner permissions (or organization owner)
  • LinearB Admin role
Step 1. Generate a Personal Access Token (PAT) in GitLab

To connect GitLab, first create a Personal Access Token:

  1. Log in to GitLab.
  2. On the left sidebar, select your avatar.
  3. Select Edit profile.
  4. On the left sidebar, select Access tokens.
  5. Select Add new token.
  6. In Token name, enter a name for the token.
  7. In Token description, enter a description (for example, LinearB Integration).
  8. In Expiration date, enter an expiration date for the token.
    The token expires on that date at midnight UTC.
    If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date.
    By default, this date can be a maximum of 365 days later than the current date. In GitLab 17.6 or later, you can extend this limit to 400 days.
    If you encounter issues due to an expired token, contact support@linearb.io.
  9. Select the required scopes (permissions).

Scope

Access

api

Complete read/write access to the API, including groups and projects, registries, and repositories (Git over HTTP).

read_user

Read-only access to the authenticated user’s profile through /user, plus read-only endpoints under /users.

read_api

Read access to the API, including groups and projects.

read_repository

Read-only access to repositories on private projects using Git over HTTP or Repository Files API.

write_repository

Read-write access to repositories on private projects using Git over HTTP.

read_registry

Read-only (pull) access to container registry images (when enabled).

write_registry

Read-write (push) access to container registry images (when enabled).

read_virtual_registry

Read-only (pull) access to images via dependency proxy (when enabled).

write_virtual_registry

Pull, push, and delete access to images via dependency proxy (when enabled).

sudo

Perform API actions as any user (admin only).

admin_mode

Perform admin API actions when Admin Mode is enabled (Self-Managed only).

create_runner

Create runners.

manage_runner

Manage runners.

ai_features

API actions for AI features such as GitLab Duo, Code Suggestions, and Duo Chat (scope behavior varies by environment/version).

k8s_proxy

Kubernetes API calls using the agent for Kubernetes.

self_rotate

Rotate this token using the personal access token API (does not rotate other tokens).

read_service_ping

Download Service Ping payload through the API (admin only).
If you enabled external authorization, personal access tokens cannot access container or package registries. Disable external authorization to use personal access tokens with registries.
  1. Select Create personal access token.
  2. Save the token somewhere safe. After you leave the page, you can’t view it again.

For more details, see the GitLab Personal Access Token Documentation .

Optional: Real-time updates with write_repository

LinearB requires write_repository permissions to configure webhooks for real-time data collection. Without this permission, LinearB still works, but data updates may be delayed by up to 2 hours.

  • This delay can impact metric accuracy and increase wait times for WorkerB notifications (for example, PR review requests).

Alternative authentication method

If write_repository cannot be granted due to security restrictions, consider using a service account:

  1. Create a GitLab service account with admin permissions for all relevant repositories.
  2. If applicable, use an existing “global admins” group to manage access.
  3. Connect the service account to LinearB using OAuth.

For more details, see GitLab’s documentation on creating groups in GitLab.

Step 2. Connect GitLab to LinearB

After generating a PAT, connect it in LinearB:

  1. In LinearB, go to Settings → Company Settings and select the Git tab.
  2. Click Add Integration.
  3. Select GitLab as your Git provider.

Select GitLab integration in LinearB

  1. Paste your Personal Access Token (PAT) into the required field.
  2. Click Connect. LinearB will begin processing your GitLab repositories.

Paste GitLab PAT and connect in LinearB

Step 3. Reauthorize your GitLab token in LinearB (expired token)

If your GitLab token expires, generate a new token and update it in LinearB:

  1. Generate a new token by following Step 1 above.
  2. In LinearB, go to Company Settings and select the Git tab.
  3. Click the three-dot menu next to your existing GitLab connection.
  4. Select Reauthorize Git and enter your new token.

Once updated, LinearB resumes processing your GitLab data.

Reauthorize GitLab token in LinearB

Troubleshooting & support
  • Ensure the PAT includes the required scopes (permissions).
  • Verify your GitLab account has access to the repositories you want to connect.
  • If issues persist, contact LinearB Support or join the Dev Interrupted Discord Server.
Related guides

Need assistance?
Visit our HelpDocs Support Page.

How did we do?

GitLab Server (On-Prem) Connection Guide

Contact