Skip to main content
Table of Contents

Connect GitLab with a Personal Access Token (PAT)

LinearB allows you to integrate GitLab with your account using a Personal Access Token (PAT).

Steven Silverstone
Updated by Steven Silverstone

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

However, you must be an organization owner or have "maintainer" or "owner" permissions for the relevant repositories to generate a PAT that grants LinearB the required.

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

1. Generate a Personal Access Token (PAT) in GitLab

To connect GitLab, you first need to 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 the token (e.g., LinearB Integration).
  8. In Expiration date, enter an expiration date for the token.
    The token expires on that date at midnight UTC. A token with the expiration date of 2024-01-01 expires at 00:00:00 UTC on 2024-01-01.
    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, please contact support@linearb.io for assistance in validating and resolving any data discrepancies.
  9. Select the required scopes (permissions)

Scope

Access

api

Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry. Also grants complete read/write access to the registry and repository using Git over HTTP.

read_user

Grants read-only access to the authenticated user’s profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.

read_api

Grants read access to the API, including all groups and projects, the container registry, and the package registry.

read_repository

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

write_repository

Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API).

read_registry

Grants read-only (pull) access to container registry images if a project is private and authorization is required. Available only when the container registry is enabled.

write_registry

Grants read-write (push) access to container registry images if a project is private and authorization is required. Available only when the container registry is enabled.

read_virtual_registry

If a project is private and authorization is required, grants read-only (pull) access to container images through the dependency proxy. Available only when the dependency proxy is enabled.

write_virtual_registry

If a project is private and authorization is required, grants read (pull), write (push), and delete access to container images through the dependency proxy. Available only when the dependency proxy is enabled.

sudo

Grants permission to perform API actions as any user in the system, when authenticated as an administrator.

admin_mode

Grants permission to perform API actions when Admin Mode is enabled. Introduced in GitLab 15.8. Available only to administrators on GitLab Self-Managed instances.

create_runner

Grants permission to create runners.

manage_runner

Grants permission to manage runners.

ai_features

This scope:

  • Grants permission to perform API actions for features like GitLab Duo, Code Suggestions API and Duo Chat API.
  • Does not work for GitLab Self-Managed versions 16.5, 16.6, and 16.7.

For GitLab Duo plugin for JetBrains, this scope:

  • Supports users with AI features enabled in the GitLab Duo plugin for JetBrains.
  • Addresses a security vulnerability in JetBrains IDE plugins that could expose personal access tokens.
  • Is designed to minimize potential risks for GitLab Duo plugin users by limiting the impact of compromised tokens.

For all other extensions, see the individual scope requirements in their documentation.

k8s_proxy

Grants permission to perform Kubernetes API calls using the agent for Kubernetes.

self_rotate

Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens.

read_service_ping

Grant access to download Service Ping payload through the API when authenticated as an admin use.

If you enabled external authorization, personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries.
  1. Select Create personal access token.
  2. Save the personal access token somewhere safe. After you leave the page, you no longer have access to the token.

For additional details, refer to the GitLab Personal Access Token Documentation.

Granting write_repository Permissions and Alternative Authentication Methods

LinearB requires write_repository permissions to configure webhooks for real-time data collection. Without this permission, LinearB will still function, but data updates will be delayed by up to 2 hours instead of occurring in real time.

  • This delay can impact metric accuracy and cause long wait times for WorkerB notifications on PR review requests and other time-sensitive updates.
Alternative Authentication Method

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

  1. Set up a GitLab service account with admin permissions for all relevant repositories.
  2. Many GitLab instances already have a "global admins" group that can manage this.
  3. Connect the service account to LinearB using OAuth for a more streamlined and secure integration.

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

2. Connect GitLab to LinearB

Once you have generated a Personal Access Token (PAT), you can integrate it with LinearB:

  1. Navigate to Settings > Company Settings, and select the Git tab.
  2. Click Add Integration.
  3. Select GitLab  as your Git provider.
  1. Paste your Personal Access Token (PAT) into the required field.
  2. Click Connect, and LinearB will begin processing your GitLab repositories.

Reauthorizing Your GitLab Token in LinearB

If your GitLab token has expired, follow these steps to reauthorize it with LinearB:

  1. Generate a new token by following the instructions in the "Generate a Personal Access Token (PAT) in GitLab" section above.
  2. In LinearB, navigate to Company Settings, and select the Git tab.
  3. Click the three-dot menu next to your existing GitLab token connection.
  4. Choose Reauthorize Git and enter your new Token ID.

Once updated, LinearB will resume processing your GitLab data without delays.

3. Troubleshooting & Support

  • Ensure the PAT has the correct scopes (permissions).
  • Verify that your GitLab account has sufficient access to the repositories you want to connect.
  • If you encounter issues, contact LinearB Support or join our Dev Interrupted Discord Server for discussions on Git and DevOps.

For additional support, visit our HelpDocs Support Page.

How did we do?

Connect Azure Repos Using a Personal Access Token

Connect Your GitHub Account to LinearB

Contact