GitLab

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

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.

Configure the GitLab integration

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

1. Navigate to Linear Settings > Workspace > Integrations > GitLab
2. Click Enable to launch the set-up pop-up.

1. Navigate to GitLab > User Settings > Personal Access Token or GitLab > Project Settings > Access Token to create an API access token.
   
   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.
2. 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.
3. (Optional) 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, 35.243.134.228, 34.140.253.14, and 34.38.87.206.
4. Click Connect.
5. Linear will generate the Webhook URL after it validates the access token. Copy and paste this URL to GitLab in either:
   1. A Group's Webhook Settings (for example your company) to integrate all projects under it.
   2. A Project's Webhook Settings, to individually connect a specific project.
6. Enable the following Triggers:
   1. Push events
   2. Comments
   3. Merge request events
   4. Pipeline events
7. Under SSL verification, ensure Enable SSL verification is checked
8. Click Save changes.

Link Merge Requests

Create a new branch

Set the branch format in Linear Settings > Workspace > Integrations GitLab > Branch format. When viewing or selecting a Linear issue, use the Copy git branch name action or shortcut Cmd/Ctrl + Shift . It will give you a branch name with the issue ID which you can use to create a new branch in GitLab.

Add the issue ID in the MR title

Include the Linear issue ID (e.g. ID-123) in the MR title when creating merge requests.

Use a magic word

Add a magic word + issue ID in the MR description (e.g. Fixes ENG-123). The integration cannot link MRs via comments or commit messages. The available magic words to link issues are: close, closes, closed, closing fix, fixes, fixed, fixing resolve, resolves, resolved, resolving complete, completes, completed, completing.

To link MRs to issues without them closing your issue, use the one of the contributing magic words: ref, references, part of, related to, contributes to, towards. The linked MR will still move the issue through other statuses per Workflow settings, but will not close the issue when the MR merges.

Link multiple Linear issues to an MR

To link multiple Linear issues to a single Merge Request, or to link a Merge Request after creating it, use the magic word linking method by including multiple closing statements in the MR description (e.g. Fixes ENG-123, DES-5 and ENG-256). Linking will happen after you save your changes. The Linear issue will not close until all Merge Requests have been closed/merged.

Merge Request automation

The merge request automation allows you to select specific statuses for your Linear issues based on MR changes—saving you the hassle of updating Linear issues manually.

Customize the MR automation in Settings > Team > Workflow. Since this is a team setting, it must be configured for each team in your workspace.

Ready for merge automation

If you'd like to use the Merge Request automation 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.

Branch-specific rules

You can 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. Linkbacks are managed by the scope selected.

Auto-assign and update status

Save yourself a few steps by toggling on our automations in Settings > My Account > Preferences > Behavior.

• Auto-assigns the issue to you, and/or
• Move the issue to the first Started status (which you can customize in Settings > Team > Workflow) when you copy the git branch name.

FAQ