Connect GitLab with a Personal Access Token (PAT)

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 and navigate to your User Settings.
2. Select Access Tokens from the menu.
3. Click Create a Personal Access Token.
4. Provide a descriptive name for the token.
5. Set an expiration date (optional but recommended for security).
   1. For optimal stability, set your Personal Access Token (PAT) to a long-term expiration date or, if possible, no expiration date. 
   2. If a GitLab token expires, it may cause data inconsistencies between the time it expires and when a new token is added.
   3. If you encounter issues due to an expired token, please contact support@linearb.io for assistance in validating and resolving any data discrepancies.
6. Assign the following scopes (permissions):
   • read_api – Read access to API resources.
   • read_api – Read access to API resources.
   • read_user – Access user profile information.
   • read_repository – Read-only access to repository content.
   • write_repository – Allows LinearB to update repository content when needed.

     

7. Click Create Personal Access Token and copy the token securely (it will not be viewable again).

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.

Related Guides

• BitBucket Server (On-Prem) Connection Guide
• Connect Azure Repos Using a Personal Access Token
• Microsoft Entra (Azure AD) - SSO Configuration

For additional support, visit our HelpDocs Support Page.