GitHub and GitLab

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

The integration works similarly for GitHub and GitLab. For ease of reading, we sometimes use the terminology "pull request" and "PRs" in this doc when referring to the integration generally but they would apply to GitLab merge requests and MRs, too. The terminology you'll see in Linear's app will match the integration you choose.

How it works

Once you connect Linear with GitHub or GitLab, you can start linking your GitHub pull requests or GitLab merge requests to Linear issues. You can link multiple Linear issues to a single GitHub or GitLab issue.

Set up pull request automation so that updates to PRs change the status of linked Linear issues. This saves you the hassle of updating Linear issues manually. Do this under General in team settings.

Features we currently do not support:

Linking or syncing GitHub or GitLab issues to Linear. See Common Questions below.

Linking multiple GitHub orgs in one workspace (this is a limitation of GitHub Apps).

Linking your user account to connect GitHub in more than one workspace (this is a limitation of GitHub Apps).drive

Features that require full code read permissions. On GitHub, we've chosen to only read pull request metadata. On GitLab, we have both read and write access with their API (they don't have separate permissions for comments).

Integrating with GitHub Enterprise. If you're interested in an integration with GitHub Enterprise, reach out. Also reach out if you have suggestions for improving the integration.

How to set up the integration

To enable your source control integration, visit Settings > Workspace > Integrations. If the setting isn't available to you, ask your workspace admin.

GitHub

To enable GitHub, click Connect GitHub in integration settings and select which repositories you want to give Linear access to. It's easy to add or remove repositories later; just visit settings through the Configure GitHub button from Linear's Github integration settings page. All teams in your workspace will be able to link to issues in the selected repositories.

GitHub Enterprise

If you're using Enterprise Cloud and have IP Allow List security setting enabled, you'll also need to turn on Enable IP allow list configuration for installed GitHub Apps setting to enable Linear's GitHub integration. Read more here. Linear doesn't currently support GitHub Enterprise Server but we're consider adding support for it.

⚠️

If you get an error when setting up your GitHub integration, or it doesn't work, try this. 1. Disconnecting the integration from GitHub's side. 2. Open Linear in the browser and reset your local database by going to linear.app/reset. 3. Reconnect the integration in Linear settings. If you're still having trouble, reach out to us via the Help & Feedback modal. Common causes: You can only connect your GitHub account to a single Linear workspace. If you want to connect your GitHub org to a second workspace, ask someone else from your org to set up the integration through their GitHub account. You can only connect one Github org to a single workspace (there are no workarounds at this time). These are limits of GitHub apps.

Security On GitHub, we don't ask permissions to read your source code. We're only using pull request metadata and therefore can't link commits which are made outside of pull requests. On GitLab, we have both read and write access with their API (they don't have separate permissions for comments).

Autolinking issues in GitHub

If you want to automatically resolve your Linear issue IDs (e.g. ENG-123) in PR descriptions or comment to links, you can enable this using GitHub's Autolink references feature. See instructions on GitHub.

Use the following URL format:

plain text
https://linear.app/workspace/issue/ID-<num>

where workspace corresponds to your workspace's URL and ID is the issue identifier key for your team. You need to add each team separately as they all have a different ID pattern.

GitLab

We support linking GitLab merge requests for both hosted and self-hosted installations, as long as your installation is publicly available. To enable GitLab, select "Connect GitLab" from integration settings.

To enable integration with GitLab, please do the following:

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.

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

⚠️

If you get an error when setting up your GitLab integration, or it doesn't work, try disconnecting it and then reconnecting again. If you're still having trouble, reach out to us via the Help & Feedback modal. Common causes: Not adding the user you created to Linear (and used to create the access token) to the group that contains all repos.

How to use the source control integration

Linking issues and branch names

Linear supports three ways to link issues with your pull requests:

Include issue ID in the branch name

Include issue ID in the PR title

Include issue ID with a magic word in the PR description (e.g. Fixes ENG-123) similar to GitHub Issues

The fastest way to link PRs to issues is to use Linear's branch name feature. It will give you a uniform branch name with the issue ID which you can use to start working on your feature or bug.

✨

ProTip: Copy the suggested branch name to your clipboard from the command menu or with Cmd/Ctrl Shift . and then paste it into your git client to start working on your issue. You can also set preferences to automatically assign the issue to yourself or move issues to In Progress status on copy.

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 GitHub/GitLab integration settings.

To link multiple issues to a single PR, you can use the magic word linking method by including multiple closing statements in the PR description (e.g. Fixes ENG-123, DES-5 and ENG-256).

If you forgot to link your PR when creating it, or you need to do it afterwards, you can modify the PR title or description. We don't support linking in comments.

The linking will happen when you save your changes.

What words can I use to link issues in descriptions?

To link a pull request to an issue, use one of the following magic words together with the ID in the PR description:

plain text
close
closes
closed
closing
fix
fixes
fixed
fixing
resolve
resolves
resolved
resolving
complete
completes
completed
completing

Issue linkbacks

When an issue is linked with a pull request, Linear posts a linkback message as a comment with the issue title and description. All the pull 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.

Pull request workflows

A key part of Linear's pull request integration is workflows.

This is a team based setting where you can set what happens to an issue's state as a PR moves from from draft to review to merge.

Linear also supports PR reverts. When reverting a PR, the linked issue will automatically re-open. From this point forward automation is disabled and it's up to you when the issue should be closed.

Common Questions

Can I import or integrate with GitHub Issues?

How do I connect a PR that is already open?

Do you support Bitbucket?

Can I remove PR links from an issue?

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

Keyboard Shortcuts

Cmd/Ctrl Shift . to copy git branch name

Did we miss something? Have a question? Email us at hello@linear.app to let us know.