Skip to main content
Sign in
Deutsch (Deutschland) Español Français Italiano Português

GitLab (Cloud + Self-Managed)

Heather Hazell
  • Updated

Connect GitLab to LinearB to start processing your Git data for delivery metrics and automation.

TL;DR

  • Generate a GitLab Personal Access Token (PAT) with api, read_user, and read_repository scopes.
  • In LinearB, go to Settings → Company Settings → Git and add a new GitLab (Cloud or Server) integration.
  • Paste the PAT, validate, then select which repositories or projects to include.

Overview

Connecting GitLab to LinearB allows LinearB to process your GitLab repositories so you can track work across projects and use delivery metrics and automation features.

What Happens After You Connect

  • LinearB starts syncing Git history for the selected GitLab projects.
  • Initial data processing can take from a few minutes to a couple of hours depending on repo size.
  • Once complete, you’ll see delivery metrics (cycle time, PR metrics, etc.) populated for those repos.

Before You Begin

Prerequisites

  • An active LinearB account.
  • Access to a GitLab account (Cloud or Self-Managed).
  • Designate a gitStream user account (using a service account is recommended)
     
Read More about Designating a gitStream User Account

gitStream automation rules are executed on behalf of the user account configured when you connect gitStream to your GitLab instance. This account must have the appropriate permissions to the relevant repositories.

  • The account must have the maintainer or owner role to the relevant repos
  • We recommend creating a dedicated service account to control access to individual repos easily. A meaningful account identifier whose name contains the string gitstream (case insensitive), such as gitStream-cm, is recommended to ensure clarity and proper identification of the automated actions
  • You can also use your professional or personal GitLab account, though this would result in all automations being executed under that account, which might also affect LinearB's metrics

Use this account when you integrate gitStream

Make sure to use this account when authorizing GitLab in LinearB.


Roles & Permissions

  • GitLab Cloud: You must be able to create a Personal Access Token (PAT) with API and repository read access for the projects you want LinearB to analyze.
  • GitLab Server (On-Prem): The GitLab user used for the integration must be a direct member of the root group as Maintainer or Owner, or a member of each project you want LinearB to access. LinearB only lists projects that this user is a member of.
  • LinearB: You must be a LinearB Admin to add or manage Git integrations.

Note: LinearB uses read-level access to analyze Git history and metadata. It does not modify your code or branches.

Expected Time to Complete

  • GitLab Cloud: ~5–10 minutes to create a PAT and connect.
  • GitLab Server: ~10–20 minutes, including any firewall/allowlisting changes.

Connect GitLab Cloud with a Personal Access Token (PAT)

Steps to Connect GitLab Cloud via PAT

Step 1 – Generate a Personal Access Token in GitLab

  1. Log in to GitLab.
  2. In the top-right, select your avatar and click Edit profile.
  3. In the left sidebar, select Access tokens.
  4. Click Add new token.
  5. In Token name, enter a descriptive name (for example, LinearB Integration).
  6. In Token description, optionally describe how the token will be used.
  7. In Expiration date, choose an expiry date for the token.
    • If you do not enter a date, GitLab sets a default expiry based on your instance settings (for example, up to 365 days; some configurations support longer).
    • When the token expires, you must generate a new one and re-authorize it in LinearB.
  8. Enable the scopes needed so LinearB can read your projects via the GitLab API. At minimum, we recommend:
    • api – API access for groups/projects and repositories over HTTP.
    • read_user – read-only access to the authenticated user’s profile.
    • read_repository – read-only access to repositories over HTTP or the Repository Files API.
  9. Optionally, you can enable:
    • read_registry – read-only access to Container Registry, if you also need registry data in other workflows.
  10. Click Create personal access token.
  11. Copy the token and store it securely. You will not be able to view it again after leaving the page.

Step 2 – Connect GitLab Cloud to LinearB

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

Reauthorizing an Expired GitLab Token

  1. Generate a new PAT by repeating the steps in Generate a Personal Access Token in GitLab.
  2. In LinearB, go to Settings → Company Settings → Git.
  3. Find your existing GitLab integration and click the three-dot menu.
  4. Select Reauthorize Git and enter your new token.

Connect GitLab Server (On-Prem)

Steps to Connecting GitLab Server

Step 1 – Select GitLab Server as Your Git Provider

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

Step 2 – Allow LinearB Access (Firewall / IP Allowlisting)

If your GitLab Server instance is accessible from the public internet, you can skip this step. If it is hosted within a private network, you must allow LinearB’s public IP addresses in your firewall:

  • 52.15.80.85
  • 54.241.87.26
  • 54.193.121.186
  • 18.118.232.229

For networks behind a VPN, ensure that a reverse proxy allows LinearB-specific access to GitLab Server.

Understanding IP Allow-listing for gitStream

When configuring IP allowlists in GitLab, you control which external IP addresses can interact with your repositories and APIs. This is important for both the LinearB/gitStream integration and any CI/CD runners in use.

  1. Webhook event handling by gitStream
    When GitLab sends a webhook (for example, when a merge request is opened), gitStream may make follow-up API calls such as retrieving metadata, posting comments, or updating merge request statuses. These calls originate from LinearB’s IP addresses listed above and must be allowlisted to prevent connectivity issues.
  2. Outbound requests from CI/CD runners
    If gitStream is used in your pipeline, runners may also make outbound calls (for example, cloning repositories or retrieving commit history). If those runners are hosted on dynamic infrastructure, their IPs can change frequently, which can cause blocked access if not allowlisted.

Recommended Solutions

  • Add LinearB’s static IPs (above) to your GitLab allowlist.
  • Use self-hosted runners with fixed IPs so their addresses can be allowlisted explicitly.

This ensures gitStream can operate reliably during both automation and pipeline execution.

Step 3 – Insert Your GitLab Server URL

  1. After allowing LinearB’s IPs, enter your GitLab Server URL in the LinearB setup screen.
  2. LinearB will automatically check connectivity.
  3. Once verified, click Continue to move to the next step.

Step 4 – Create a Personal Access Token in GitLab Server

  1. Log in to your GitLab Server instance and click your avatar in the upper-right corner.
  2. Select Settings from the dropdown menu.
  3. In the user settings menu, navigate to Access Tokens.
  4. Enter a name for the token and optionally set an expiry date.
  5. Enable the following access scopes:
    • read_user
    • api
    • read_repository
    • write_repository
  6. Click Create Personal Access Token.
  7. Copy the token immediately (it will not be visible again) and store it securely.

Step 5 – Validate and Connect

  1. Paste the personal access token into the LinearB setup interface.
  2. LinearB will automatically validate the token.
  3. After validation, choose which repositories or projects you want LinearB to analyze, then save.

Verify the Integration

  • In LinearB, go to Settings → Company Settings → Git and confirm that GitLab (Cloud) and/or GitLab Server appears as Connected.
  • Open the GitLab integration entry and check that repositories or projects are available for selection.

Troubleshooting

Problem Likely Cause Fix
Some repositories are not visible in LinearB The integration user is not a member of the group or project in GitLab, or does not have sufficient permissions. Add the integration user as a member (with the appropriate role) of the missing group or project for that repo(s), then refresh the repository list in LinearB.
GitLab PAT is rejected or validation fails The PAT is missing required scopes, has expired, or was copied incorrectly.
  • Confirm that the token includes the required API and repository scopes listed above.
  • Check the expiry date and create a new PAT if necessary.
  • Paste the new token into LinearB and use the Reauthorize Git option if you are updating an existing connection.
Self-hosted server not connecting Firewall or private network issue preventing LinearB from reaching your GitLab Server URL. Ensure LinearB can reach the server URL from the public internet, and that the LinearB IPs are allowlisted as described above.
Webhooks or real-time updates are delayed Webhooks are not configured correctly, or network policies are blocking webhook/API calls.
  • Verify that webhook configuration for GitLab is valid and active.
  • Confirm that your firewall or IP allowlists are not blocking calls from LinearB’s IP addresses.

FAQs

Do I have to grant write_repository to LinearB?

For GitLab Server, write_repository is required in the PAT scopes documented above so LinearB can perform the necessary API operations. For GitLab Cloud, use the minimum scopes your security policies allow while still enabling LinearB to read repository data and manage any required webhooks.

What happens if my GitLab token expires?

If your token expires, LinearB will stop processing new GitLab data until a new token is generated and re-authorized. Create a new PAT in GitLab and use the Reauthorize Git flow in LinearB to restore processing.

Can I use a service account instead of a personal user account?

Yes. You can create a GitLab service account with the required permissions for all relevant repositories and connect that account to LinearB to centralize access management.

Next Steps

Related articles

Comments

0 comments

Article is closed for comments.