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:

• 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 since issues between Linear and GitHub. This will create a synced thread in the Linear issue so comments will sync both ways.

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.

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.

Properties that are synced between Linear and GitHub issues include:

• Title
• Description
• Status
• 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.

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

Commit linking

We use GitHub webhooks to link commits, which do not require permission to reach your codebase.

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. Refer back to Linear for the settings to configure in GitHub.
5. Click Add webhook.
6. Go back to Linear and click Done.

Link to a Linear issue

Link pull requests

You can link PRs to issues in three ways:

• Include the issue ID in the branch name
• Add the issue ID in the PR title, or
• Preface 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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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