GitHub

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

Overview

The GitHub integration offers two core functionalities:

Permissions

The integration needs the following permissions for Pull Requests and GitHub Sync:

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

Linking Linear issues to commits is handled through GitHub webhooks, which do not require access to your codebase.

To grant Linear organization-level access in GitHub, the integration must be installed by a GitHub organization owner. If you only need repository-level access, a repository administrator can install the integration instead.

Configure

Enable the GitHub integration

1. Go to Setting > Features > 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 personal Github account

GitHub Enterprise options

If it's relevant to your organization, GitHub Enterprise Cloud and GitHub Enterprise Server require additional setup compared to GitHub.com. See the following section for details of each.

The table below provides a comparison of available features across GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server.

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

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.

Personal account connection

In addition to the organization-level setup, each member should connect their personal GitHub account. This ensures that the activity feed, synced comments, and assignees are mapped directly to the connected user in Linear, rather than appearing as generic GitHub activity.

To connect your account, navigate to Settings > Connected accounts. Once connected, any synced activity from GitHub will be correctly attributed to you in Linear.

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

Configure GitHub Issues Sync

Watch this video to see how GitHub Issues sync works:

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

You can choose to sync:

• One-way: issues created in GitHub will create a synced copy in Linear, or
• Two-way: issues created in either the GitHub repo or Linear team will create a synced copy in the other software

Multiple repositories can be connected to create issues to a single Linear team through one-way sync when issues are created in GitHub. However, only one repo can be configured for two-way sync at a time.

You can enable two-way sync when connecting a repo to Linear, or change this to another repo by pressing ... > Edit Link on an existing repo connection.

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
  Linear users can connect their GitHub account from https://linear.app/settings/account/connections to be synced as the issue assignee
• Labels
• Sub-issues
  Multi-level & cross-repository/team hierarchies are supported. If parent issue is not a synced issue (e.g. it's in a different GH repo/Linear team), the sub-issue can still get synced, but will have no parent issue set on the other end.
• 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. You can also transfer GitHub issues between two synced repos; this will appropriately update the team of the associated issue in Linear.

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

Issue sync banners

Once an issue is synced between GitHub and Linear, a banner will appear at the top of the issue to make this clear. The banners will display information to show current sync status or will surface any errors with syncing.

Linking Linear issues to GitHub PRs

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

Watch this video for a quick demo on the available linking methods:

Link through pull requests

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. The Linear issue status will be updated when the final linked PR moves to the required state from your workflow.

For example if you have 2 PRs linked to 1 issue, you'll need merge both PRs before the Linear issue status will change.

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 reaches the default branch.

Viewing a linked Linear issue

Remove a PR from an issue

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.

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.

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, Netlify, Cloudflare and AWS Amplify 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," once these are added by the PR author or a GitHub bot.

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.

Pull request preview link accepted formats

PR description textVercel Preview commentsNetlify Preview comments

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

Workflow automation

Issue status updates

Updates to PRs can automatically update the status of their linked Linear issues.

Watch this video to explore more about how issue status automation works:

You can customize the automation in Settings > Team > Issue statuses & automations > 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.

Custom merge queues

If you use a custom merge queue that merges changes and then closes the pull request, be sure to add the externally-merged label before closing it. This tells Linear to treat the pull request as successfully merged even though it was closed.

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. Please note that "ready to merge" automations will not fire if a "review request or activity" automation is not also configured.

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”

Watch this video to visualize how branch-specific rules work:

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.

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.

Other settings

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—including any images or attachments that exist within the 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.

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