Skip to content →

GitHub

Linear supports linking your GitHub pull requests, automating workflow statuses, and syncing issues between GitHub and Linear.

Linear logo and Github logo

Overview

The GitHub integration offers two core functionalities:

  • Link Linear issues to GitHub pull requests and/or commits: Automate your issue status by linking to a GitHub pull request or commit to follow their progress.
  • Sync GitHub issues with Linear issues: You can link Linear teams to GitHub repos of your choice, to automatically create and sync issues between Linear and GitHub. This will create a synced thread in the Linear issue so comments will sync both ways.

The integration requires the following permissions for PRs and Github Sync:

  • Read access to checks and metadata
  • Read and write access to issues and pull requests

For linking Linear issues via commits, we use GitHub webhooks to link commits, which do not require permission to reach your codebase.

Configure

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

Pull request linking

  1. Go to Setting > Workspace > Integrations > GitHub
  2. Click Enable
  3. Select the GitHub organization you want to connect.
  4. Select All repositories or Only select repositories and choose the repositories you want to connect.
  5. Click Install.
  6. Authenticate into your Github account.

GitHub Enterprise Cloud

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, 35.243.134.228, 34.140.253.14, and 34.38.87.206. Linear doesn't currently support GitHub Enterprise Server.

GitHub Enterprise Server (self-hosted)

If you're self-hosting GitHub Enterprise, you'll need to install it using GitHub Enterprise Server integration which is separate from the regular GitHub integration. Currently it supports pull request linking with issues, but doesn't support issues sync and commit linking.

The integration doesn't require firewall modifications, but it will require installation of Linear's GitHub App into your GitHub instance. This is guided during the install process. If you'll need help setting it up, please contact us.

GitHub Issues Sync

From the GitHub Issues section of the GitHub integration settings, click the + icon, then select the GitHub repo and Linear team to link.

Setup for GitHub Issues Sync.

You can choose to sync in only one direction so issues created in GitHub will create a synced copy in Linear, or bidirectionally so that issues created in the relevant Linear team create a synced copy in GitHub as well.

Multiple repositories can be linked to a single Linear team, but Linear will only create issues in one of these repositories. With multiple repositories connected bidirectionally, you change which one will be used for issue creation from ... > Set as default in Linear's Github settings.

GitHub Issues Sync will only sync newly created issues. To sync existing GitHub Issues, you will have to import them. Refer to the Importer page.

Properties that are synced between Linear and GitHub issues include:

  • Title
  • Description
  • Status
    Please note that any custom statuses set at the GitHub Project level do not sync to Linear.
  • Assignee
  • Labels
  • Comments
    Comments made not in the synced thread of the Linear issue will not get synced to the GitHub issue. This allows for private discussions.

Moving GitHub synced Linear issues between Linear teams will maintain the synced relationship.

To manually stop syncing, remove the attachment from the Linear issue through its overflow menu.

Moving GitHub issues between repos is not supported with our GitHub sync feature. Doing so will create duplicate Linear issues.

Commit linking

  1. Turn on the toggle for Link commits to issues with magic words at the bottom of the GitHub settings page.
  2. Go to Settings -> Webhooks in your GitHub organization or repository.
  3. Click Add webhook button
  4. Input the Payload URL and Secret provided in Linear, and select application/json content type. Leave "Push events" selected.
  5. Click Add webhook.
  6. Go back to Linear and click Done.
Setting to enable commit linking

Link to a Linear issue

You can link a Linear issue using pull requests or commits.

Link using pull requests

Include issue ID in the branch name

Use the Copy git branch name action or shortcut Cmd/Ctrl Shift . when viewing or highlighting/selecting an issue and paste it into the new branch name in GitHub.

Method

Use a magic word + issue ID in the PR description or title (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

Linear offers closing and non-closing magic words for you to customize your workflow. When using a closing magic word, Linear will move the issue to In Progress when the branch is pushed and Done when the commit is merged to the default branch. When using a non-closing magic word, 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.

The closing magic words are: close, closes, closed, closing fix, fixes, fixed, fixing, resolve, resolves, resolved, resolving, complete, completes, completed, completing.

The non-closing magic words are: ref, references, part of, related to, contributes to, towards.

Link multiple issues

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.

Link multiple PRs to one Linear issue

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.

Include the Linear issue ID (e.g. ID-123) in the title when creating pull requests.

To remove a PR from a Linear issue, open the issue, click on the three dots on the PR attachment, and select Remove. You can also do this through the command menu in Linear by viewing or selecting an issue, then searching for git.

To link a PR that is already open, modify the PR title or description to link an issue.

Link using commits

Use a magic word before the issue ID in commit message to link issues. We'll move the issue to In Progress when the commit is pushed and Done when the commit is merged.

Pull request preview links

If your PR contains one or multiple preview links, this will add a preview link shortcut to the Linear issue.

Preview links are automatically detected for popular platforms like Vercel and Netlify if you have connected Linear with your GitHub repository. We also support custom preview links: pull request descriptions and comments are parsed for any markdown links ending with "preview". Multiple previews for a single PR are available in a dropdown menu, with customizable names and icons for easy identification (e.g. mobile and desktop previews). Icons are automatically chosen to reflect best their name, such as a mobile icon for mobile release links. Preview links are automatically removed after 30 days of inactivity on the PR.

Preview links on a Linear issue

Pull request preview link accepted formats

Links that end with "preview" in your PR descriptions and comments will get added to the Linear issue as a preview link.
For example:

PR containing preview links

Vercel comments with the following format will be added as a preview link in your Linear issue.

Vercel preview comment in GitHub

Netlify comments with the following format will be added as a preview link in your Linear issue.

Netlify PR comment with preview

Workflow automation

Issue status updates

Updates to PRs can automatically update the status of their linked Linear issues. Customize the automation in Settings -> Team -> Workflow -> Pull request and commit automation. Since this is a team setting, it must be configured for each team in your workspace. You can configure status updates when PRs are drafted, opened, have a review requested, are ready for merge, and merged. By default, we will move linked issues to "In Progress" when PRs are open and "Done" when PRs merge.

Pull request and commit automation

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.

PR comments and approved state displayed in Linear attachment.

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.

Branch protection rules

Once a review is requested, if you do not have branch protection rules set up in GitHub, the issue will skip the "review request or activity" state and move to "ready to merge”. Without branch protection rules, a PR is considered always mergeable.

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.

Auto-assign and move issue to start

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. To set up this automation, refer to Preferences.

GitHub integration settings

Add multiple GitHub organizations

Click the + icon under Connected organizations to add another Github organization. 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 will only be able to use commit linking with a single GitHub org.

It is not possible to connect multiple Linear workspaces to a single GitHub organization. This is a limitation on GitHub's side. GitHub Apps can only be installed once for a GitHub organization so this means only one Linear workspace can be connected.

Branch format

Select the branch format you want to use when copying the branch name using Cmd + Shift + . from a Linear issue and pasting it into your branch name.

Branch format setting

Linkbacks

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.

If enabled for private teams, the issue titles will not be included in the comment. The link will go to your Linear issue and be accessible only by users who are part of that private team.

Setting for enabling or disabling linkbacks.

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.

FAQ

If you get an error when setting up your GitHub integration, or it doesn't work:

  1. Disconnect the integration from GitHub's side.
  2. Open Linear in the browser and reset your local database by going to https://linear.app/reset.
  3. Reconnect the integration in Linear settings.

These are the most common causes of errors:

  • The integration got out of sync. In this case, reconnecting and resetting should fix it.
  • You can only connect your GitHub account to a single Linear workspace. The workaround is to ask someone else from your org to set up the integration.

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

Make sure you completed the following steps during integration installation:

  1. Copied the provided webhook secret and saved it when creating the Linear GitHub App for your GHES instance. Without the secret, Linear is unable to verify requests
  2. Installed the newly created app to organizations and their repos you wish to link

If you missed the step 1 during installation, you'll need to Disconnect the integration inside Linear, and remove the installation inside your GitHub's developer settings, and re-install.

If you haven't completed the step 2, but successfully created the app, you can link new organizations and repositories under "Install App" in the application's developer settings.

If you have added new organizations, or repositories, they will also need to be linked to the application under developer settings under the "Install App" menu.

For the "Ready for merge" workflow to trigger, either review or checks are required within GitHub for this PR. Without either of these, the "Ready for merge" workflow will not trigger.

GitHub workflow settings
GitHub workflow settings

If you have already merged multiple PRs into a single branch and you want to merge that branch into a new branch, we will not auto-detect any Linear issues that were linked in the previous PRs. You will need to link each issue anew. You can do this by mentioning the Linear issue IDs in the new PR title or by mentioning them alongside magic words in the PR description.

Previous

Front

Next

GitLab