GitHub

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

Overview

The GitHub and GitLab integrations move issues from In Progress to Done automatically so you never have to update issues manually. It takes less than a minute to connect GitHub to the workspace and then go to team settings to configure the automatic updates.

Linear's GitHub integration is so perfect it tickles my brain. It ties task management to git. From git-blame to GitHub PR to Linear task, all linked. I love the way you "stumble towards success" using it, as long as you start with the right branch name.

Majd Taby, Darkroom

Link Linear issues to GitHub pull requests. Automate your PR workflow so that issues update when PRs are drafted, opened, merged, and when reviews are requested. You can link single or multiple issues to a specific PR. The integration also autolinks Linear issue IDs in GitHub conversations. 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

Configure

Go to Settings to enable the GitHub integration. The GitHub integration doesn't require much beyond authenticating to GitHub and choosing what statuses to apply when PRs are created, request review, and merged.

Connect GitHub

To enable GitHub, click Connect Linear with GitHub Pull Requests 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.

If you want Linear to have organization-level access to GitHub, then a GitHub organization owner will need to install the app within Linear. If you don't require GitHub organization-level access, then a repository administrator can install GitHub.

All teams in your workspace will be able to link to issues in the selected repositories.

Enable Commit Linking

You can also connect Linear with Github Commits. Linking commits to Linear issues is an additional workflow from Pull Requests. Using commit linking you can link and close Linear issues directly from your commit messages.

Connect Multiple GitHub organizations

Once you've connected one GitHub organization, go back to the integration settings page. Select the three dot menu in the Connect Linear with GitHub pull requests section (which should show Enabled) and choose the Connect new organization option. This will take you through the same flow as when you connected the first organization. Currently, we support multiple organizations for the PR automation only; you'll only be able to use commit linking with a single GitHub org.

GitHub Enterprise

If you're using GitHub 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 considering adding support for it.

Enable Autolink

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:

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

If you change your Linear team name/ID, you may need to reconfigure the Autolink settings.

Basics

Link PRs

Once you connect Linear with GitHub, you can start linking your GitHub pull requests to Linear issues.

You can link PRs to issues three ways: by including the issue ID in the branch name, adding the issue ID in the PR title, or prefacing an issue ID with a magic word in the PR description (e.g. Fixes ENG-123).

Branch name

Include *issue ID* in the branch name to link the issue to a Pull/Merge Request.

The fastest way to link to issues is to use Linear's branch name feature. Set the branch format in the integration 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 integration settings.

PR automation

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.

Customize the PR automation in team settings under Workflow. By default, we'll move linked issues to In Progress when PRs are open and Done when PRs are merged. You can configure status updates when PRs are drafted and request review. Since this is a team setting, it must be configured for each team in your workspace.

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. When your pull request is being reviewed in GitHub, 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.

If you don't see review state indicators, check your GitHub settings to see if Linear has requested updated permissions.

Link multiple PRs

You can link multiple Linear issues to a single PR by using magic words. You can link multiple PRs to a single Linear issue using any linking technique. We won't close the Linear issue until all PRs have been closed.

Auto-assign and update status

Save yourself a few steps by toggling on our automations that auto-assign 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. To set up this automation for your account, please go to account preferences.

Immediate notifications

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 PR 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 PR merge so that you can let them know a feature shipped or bug was fixed.