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⁠

Can I import or sync GitLab issues?

Our issue migration assistant does not support GitLab issues. We suggest customizing the CLI importer to import issues. One option is to customize the importer to support GitLab imports. Another option is to export GitLab issues to a CSV and then modify the headers and format so that it matches one of the issue trackers supported by the CLI.

How do I connect a MR that is already open?

Modify the MR title or description to link an issue. See the section on this page titled Linking MRs to issues.

How do I remove a MR from an issue?

Open the issue in Linear and right click on the merge request attachment to bring up an option to remove it. You can also do this through the command menu in Linear by viewing or selecting an issue, then searching for git.

I get a notification in Linear every time a MR is open. How can I change this?

Go to integration settings and remove linkbacks. This should reduce the notifications.

My issue title is not showing up in GitLab comments, just the issue ID. Why?

If your team is private, we won't disclose the issue title. The link will go to your Linear issue and be accessible only by users who are part of that private team.

What permissions do the integrations require?

On GitLab, we have both read and write access with their API (they don't have separate permissions for comments).

Why does Linear need an access token?

During integration setup, Linear requires an access token. The below is an exhaustive list of how that token is used:

• To get supplemental information about merge requests that isn't included in the webhooks we receive
• For posting linkbacks on linked merge requests
• To retrieve merge request information when linking an MR to an issue (for rich attachment)
• To retrieve merge request mergeability status when a pipeline completes

Why are my Linear issues not progressing to my "On MR ready for merge" status?

We currently only allow issues to transition to the status you've chosen for "On MR ready for merge" if you also have a status selected for "On MR review request or activity". Make sure that you have a status selected for this event.

My GitLab integration stopped working

In GitLab's webhook settings, check that the webhook used for Linear is active. If it isn't, please send take a screenshot of its recent events and send it into support@linear.app for further support.

In the meantime, please click the "Test" button for the relevant webhook and confirm if you continue to see issues with the integration.