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 GitHub PRs | Sync GitHub issues |
|---|---|
Automate your issue status by linking to a GitHub pull request or commit to follow their progress. | Sync 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 This will only sync issues going forward. To import and sync historical GitHub Issues, refer to our GitHub Issues Importer. |
Permissions
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
- Go to Setting > Features > Integrations > GitHub
- Click Enable
- Select the GitHub organization you want to connect.
- Select All repositories or Only select repositories and choose the repositories you want to connect.
- Click Install.
- 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.
GitHub Enterprise Server (self-hosted)
We've expanded Linear's pull request automation to self-hosted GitHub Enterprise Server. You can now install the new integration to link Linear issues with a GitHub instance that's hosted in a custom URL. This integration doesn't require new firewall rules.
GitHub Enterprise Server will support the majority of the functionality of our existing GitHub integration with the exception of GitHub issue syncing and commit linking. GitHub.com and Enterprise Cloud users should use our standard GitHub integration instead.
Commit linking
- Turn on the toggle for Link commits to issues with magic words at the bottom of the GitHub settings page.
- Go to Settings -> Webhooks in your GitHub organization or repository.
- Click Add webhook button
- Input the Payload URL and Secret provided in Linear, and select
application/jsoncontent type. Leave "Push events" selected. - Click Add webhook.
- Go back to Linear and click Done.
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:
- 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.
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:
TitleDescriptionStatusPlease note that any custom statuses set at the GitHub Project level do not sync to Linear.AssigneeLinear users can connect their Github account from https://linear.app/settings/account/connections to be synced as the issue assigneeLabelsSub-issuesMulti-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.CommentsComments 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.
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
You can link a Linear issue using pull requests or commits.
Link pull requests
Branch name | Pull request title | Magic words |
|---|---|---|
Include 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. | Include the Linear | Method Use a 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: The non-closing magic words are: |
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 requires 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 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.
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.
To link a PR that is already open, modify the PR title or description to link an issue.
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
Links that end with "preview" in your PR descriptions and comments will get added to the Linear issue as a preview link.
For example:
Vercel comments with the following format will be added as a preview link in your Linear issue.
Netlify comments with the following format will be added as a preview link in your Linear issue.
Workflow automation
Issue status updates
Updates to PRs can automatically update the status of their linked Linear issues. 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.
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. 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”
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.
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.
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
If you get an error when setting up your GitHub integration, or it doesn't work:
- Disconnect the integration from GitHub's side.
- Open Linear in the browser and reset your local database by going to https://linear.app/reset.
- 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.
Make sure you completed the following steps during integration installation:
- 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
- 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.
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.