Linear supports linking your issues to GitLab and automates your merge request workflows.
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 the
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 18.104.22.168 and 22.214.171.124.
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:
Merge request events
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.
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.
- 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.
If you'd like to use this automation (pictured above) to capture passing CI checks, please verify in GitLab that:
- You have enabled Pipeline events under the Webhook settings for any repo part of the GitLab integration.
- All pipelines that Linear should consider when determining if an MR is mergeable need to be merge request pipelines. GitLab documentation is available here.
- 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.
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.
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.