GitLab

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

Linear and GitLab logos

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

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

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 api scopes for it.

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 whitelist IPs, they are listed here: 35.231.147.226 or 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 and Merge request events
  • Check Enable SSL verification

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).

Include *issue ID* in the branch name to link the issue to the MR.

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.

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.

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.

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. This makes it faster to reference without jumping between apps. You can disable linkbacks in private or public repositories in the integration settings.

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.

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.

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.