Skip to content →

GitLab

Linear supports linking your issues to GitLab and automates your merge request workflows.

Linear and GitLab logos

Overview

Link Linear issues to GitLab merge requests. Automate your MR workflow so that issues update when MRs are drafted, opened, merged and when reviews are requested. You can link single or multiple issues to a specific MR.

If you're having issues with the integration, see debugging suggestions for common problems in the FAQ.

Cmd/Ctrl Shift . to copy git branch name

G then S to go to Settings to set up integration and Team settings to set up PR workflow automation

Configure

Hosting

We support linking GitLab merge requests for both hosted and self-hosted installations, as long as your installation is publicly available.

Steps

Go to Settings to enable the GitLab integration and follow the prompts to input the following information.

Create an API Access Token (User Settings → Access Tokens)

An access token is used to query the GitLab API for further information and also used to post issue linkbacks. Because GitLab doesn't support bot accounts, linkbacks are created under the name of the token owner. It's recommended that you create a new user for Linear to act as the bot account.

When creating the token, set the api or read_api scope. If the read_api scope is selected, Linear will not post linkbacks to the issue on GitLab merge requests. If using a project access token, the token needs Reporter role or higher.

Custom GitLab URL

Enable and set a custom URL for your self-hosted GitLab installation without any path (e.g. https://gitlab.yourcompany.com). This URL needs to be accessible to public Internet and is only required for self-hosted installations.

If you need to grant access to Linear's IPs, they are 35.231.147.226 and 35.243.134.228.

GitLab webhook (Webhook Settings → URL)

After you've added the access token, the last step is to set Linear's GitLab webhook. Linear will give you the Webhook URL after it validates the access token. Copy and paste this URL to either:

  • A Group's Webhook Settings (for example your company) to integrate all projects under it
  • A Projects' Webhook Settings, to individually connect specific projects

In both cases make sure you enable following settings:

  • Triggers: Push events
  • Merge request events
  • Comments
  • Pipeline events
  • Check Enable SSL verification

Basics

Link MRs

You can link MRs to issues three ways: by including the issue ID in the branch name, adding the issue ID in the MR title, or prefacing an issue ID with a magic word in the MR description (e.g. Fixes ENG-123).

Branch name

The fastest way to link MRs to issues is to use Linear's branch name feature. Set the branch format in GitLab settings, then use the Copy git branch name action or shortcutCmd/Ctrl Shift . when viewing or selecting an issue. It will give you a uniform branch name with the issue ID which you can use to start working on your feature or bug. You will need to use this exact branch name to ensure linking takes place successfully.

We recommend using common branch naming patterns throughout your teams.

  • Good branch names are descriptive and helpful as you browse through commits.
  • Linear's default branch name consists of your username, issue ID and the issue title which incorporates the most essential information about the issue (e.g. lauren/ENG-123-fixing-loading-issue).
  • If your team prefers another pattern, you can always change it in the GitLab integration settings.

Once you connect Linear with GitLab, you can start linking your merge requests to Linear issues.

MR automation

Set up merge request automation so that updates to MRs change the status of linked Linear issues. This saves you the hassle of updating Linear issues manually.

Customize the MR automation in team settings under Workflow. By default, we'll move linked issues to In Progress when MRs are open and Done when MRs are merged. You can configure status updates when MRs are drafted and request review. Since this is a team setting, it must be configured for each team in your workspace.

MR status automation set for the following categories: on draft mr open, on mr open, on mr review request, on mr ready for merge, on mr merge

Ready for Merge automation

If you'd like to use this automation (pictured above) to capture passing CI checks, please verify in GitLab that:

  1. You have enabled Pipeline events under the Webhook settings for any repo part of the GitLab integration.
  2. All pipelines that Linear should consider when determining if an MR is mergeable need to be merge request pipelines. GitLab documentation is available here.
  3. Under ‘Merge requests’ in project settings, ‘Pipelines must succeed’ is checked.

If you want to capture MR approvals, please verify that:

  • Under ‘Merge requests’ in project settings, MR approvals are required.

Branch-specific rules

You can also set custom workflow automations based on particular target branches. For example, you can now configure that when a MR is merged to:

  • staging, the issue status should change to “In QA”
  • main, the issue status should change to “Deployed”

You can also override a default rule in a particular branch with “no action” if desired, so that issues linked to a change in that branch will not change status. Branch rules can be specified using regex, e.g: ^fea/.* can set automations for all feature branches.

Issue linkbacks

When an issue is linked with a merge request, Linear posts a linkback message as a comment with the issue title and description. All the merge requests are also listed in the issue details in Linear. When your MR is being reviewed in GitLab, see the avatars of up to three most recent reviewers and their review states without leaving Linear. This cross-referencing makes it faster to retain context without jumping between apps.

You can disable linkbacks in private or public repositories in the integration settings.

Link multiple MRs

You can link multiple Linear issues to a single MRs or multiple MRs to a single Linear issue. We won't close the Linear issue until all MRs have been closed.

Auto-assign and update status

Save yourself a few steps by toggling on our automations that auto-assigns the issue to you and move it to a started status when you copy the git branch name. The issue moves to the first started status in your team's workflow, which you can customize under team settings > workflow.

Immediate notifications

Our Git integrations speed up communication between developers and the rest of your team. Anyone subscribed to an issue will get a notification that it's been completed immediately upon MR merge (this includes creators of the issue, who are subscribed by default).

If you set up the Slack integration for team or project notifications, it'll send an update to the selected channel. If you've connected one of our customer support integrations, conversations with affected users will be re-opened automatically upon MR merge so that you can let them know a feature shipped or bug was fixed.

FAQ