Skip to content →

GitHub

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

Linear logo and Github logo

Overview

The GitHub integration automates issue status changes so you don't have to update issues manually. It takes less than a minute to connect GitHub to the workspace and customize the automatic updates.

Link Linear issues to GitHub pull requests and commits. 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 Enable in integration settings and select which repositories you want to give Linear access to. It's easy to add or remove repositories later; just click on Connected on the relevant organization and choose Configure.

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.

Connect Multiple GitHub organizations

Once you've connected one GitHub organization, go back to the integration settings page. Select + under Connected organizations to add another. 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. Alternatively you can grant access to Linear's IP addresses 35.231.147.226 and 35.243.134.228.

Linear doesn't currently support GitHub Enterprise Server.

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 in three ways: by including the issue ID in the branch name, adding the issue ID in the PR title, or prefacing an issue ID or URL with a magic word in the PR description (e.g. Fixes ENG-123 or Fixes https://linear.app/workspace/issue/ENG-123/title). If the issue is unassigned when linking takes place, you will be added as the assignee of the issue.

Magic words

Use the magic word linking method to link multiple issues to a single pull request or to link to a pull request after creating it.

To link multiple issues to one PR, include multiple issue IDs after the magic word in the description (e.g. Fixes ENG-123, DES-5 and ENG-256). Linking will happen after you save your changes. Magic words must be used in the PR description, they will not work if linked in a comment on the PR.

You can also use magic words in commit messages to link issues. We'll move the issue to In Progress when the branch is pushed and Done when the commit is merged to the default branch.

You can use the following magic words to link issues: close, closes, closed, closing fix, fixes, fixed, fixing, resolve, resolves, resolved, resolving, complete, completes, completed, completing

To link PRs or commits to issues without them closing your issue, use one of the contributing magic words next to your issue ID in the PR/Commit description: ref, references, part of, related to, contributes to, towards. The linked PR or commit will still move the issue through other statuses per Workflow settings, but will not close the issue when the PR or commit merges.

PR automation

Set up pull request automation so that updates to PRs automatically update the status of linked Linear issues.

Customize the PR automation in Settings -> Team -> 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, request review, and are ready for merge. Since this is a team setting, it must be configured for each team in your workspace.

An issue will not move from PR Open -> Ready for merge directly, so we require a review to be requested (on PR review request/activity) before transitioning to Ready for Merge.

Screen capture of workflow settings with status selections selections for on draft pr open, on pr or commit open, on pr review request, on pr ready for merge, on pr or commit merge

Branch-specific rules

You can also set custom workflow automations based on particular target branches. For example, you can now configure that when a PR 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.

Image shows a set of default rules, rules specific to a "staging" branch, and rules specific to the main branch.

PR review state

When individual reviewers comment, request changes, or approve your PR, we'll display their avatars and their actions on the GitHub attachment visible on the linked Linear issue. You can use this feature to quickly parse the review state of your PR without needing to return to GitHub.

If you request a team review instead of a review from specific individuals, we display "review requested" or "in review" on the GitHub attachment in place of user avatars.

If you're not seeing this behavior, please reinstall the GitHub integration as a first step.

Link Commits

You can also connect Linear with GitHub Commits. Linking commits to Linear issues is a separate workflow from Pull Requests and can be configured in Settings. Using commit linking you can link and close Linear issues directly from your commit messages.

Use magic words before the related issue ID in commit messages to link issues (e.g. Fixes ENG-123). We'll move the issue to In Progress when the commit is pushed and Done when the commit is merged.

GitHub Issue sync

You can link Linear teams to GitHub repos of your choice, to automatically sync and create an issue in Linear when a new issue is created on GitHub. This will create a synced thread in the Linear issue so that comments will sync both ways. Comments in the Linear issue that are not in the synced thread will not get synced across, if you want to have private discussions.

You can connect your Github issues to your desired teams on Linear from the settings under GitHub Issues.

To manually stop syncing, you can remove the link or choose the "Stop syncing…" option in the menu of the synced thread.

Entities that are synced between Linear and GitHub issues:

  • Title
  • Description
  • Status
  • Assignee
  • Labels
  • Comments*

*Comments in the Linear issue that are not in the synced thread will not get synced across, if you want to have private discussions.

To optionally sync newly created Linear issues to GitHub issues, you can toggle the setting under the … menu for the connected repository and open "Edit link".

Issue linkbacks

Automatically comment in GitHub with a link to the Linear issue. When an issue is linked with a pull request, commit or GitHub Issue, 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 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.

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.

FAQ