Linear-GitHub Sync Broken? Fix Every Failure Mode

Most Linear-GitHub failures come down to three things: the PR is missing a valid issue reference, the team’s pull request automation points at a status your workflow doesn’t use, or the GitHub App lost permissions after a repo move. A green Connected badge only means OAuth succeeded. It does not mean webhooks are delivering or that your branch name matched a real issue ID.

This page is the troubleshooting companion to our Linear vs GitHub Issues comparison. Everything below is checked against Linear’s GitHub docs on October 9, 2026.

I implement work-management platforms for a living (my firm, SSPM, is a Smartsheet partner). I don’t need Linear to win. I need your PR to show up on the issue.

First, find out which half is broken

1. Open Settings → Features → Integrations → GitHub in Linear. If you see an error banner, fix that before anything else.
2. Confirm the GitHub organization is listed and the repository is included (All repositories or your explicit list).
3. Confirm each engineer connected their personal GitHub account under Settings → Connected accounts. Org install alone is not enough for clean attribution.
4. Check the issue ID format: exact team key + number, case-sensitive (ENG-123, not eng-123 or Eng 123).
5. Check where the ID lives: branch name, PR title, or a magic word in the PR description (comments never link).
6. Open the Linear team settings → Workflows & automations → Pull request and commit automations. This is per team, not workspace-wide.
7. If nothing else works: disconnect on GitHub’s side → visit linear.app/reset → reconnect from Linear. That is Linear’s own documented fix for an integration that got out of sync.

1. PRs aren’t linking to issues

Symptom: PR opens on GitHub, Linear issue stays untouched, no GitHub attachment on the issue.

Usual causes:

• Branch name doesn’t include the issue ID. Use Linear’s Copy git branch name action (Cmd/Ctrl + Shift + .) so the format matches what you configured under Branch format.
• Issue ID is only in a PR comment. Linear says linking happens from the branch name, PR title, or magic words in the title or description. Comments do not create links.
• Wrong team key. ENG-123 will not match a Design team whose key is DES.
• Repo not in the GitHub App’s selected repository list.

Fix: edit the PR title or description to include Fixes ENG-123 (or your ID), save, and wait a few seconds. To link multiple issues: Fixes ENG-123, DES-5, and ENG-256.

Magic words worth memorizing

From Linear’s docs:

• Closing (apply On PR/commit merge status): close, closes, closed, closing, fix, fixes, fixed, fixing, resolve, resolves, resolved, resolving, complete, completes, completed, completing, implement, implements, implemented, implementing, and linear issue.
• Non-closing (link without Done-on-merge): ref, refs, references, part of, contributes to, toward, towards.
• Relation only: relates to, related to.
• Block linking: skip ENG-123 or ignore ENG-123 – use this when the branch name contains an ID you do not want linked (Linear will keep re-linking on push otherwise).

You can also create an issue from a PR by putting {TEAM}-NEW in the description (example: ENG-NEW). On Business/Enterprise, Linear uses AI for title/labels; on other plans it uses the PR title.

2. Issues don’t close when the PR merges

Symptom: PR merges, Linear issue stuck in In Progress (or whatever your “opened” status is).

Usual causes:

• You used a non-closing magic word (ref, part of, …). The link exists; Done-on-merge will not fire.
• Multiple PRs are linked to one issue. Linear updates the issue when the final linked PR reaches the required state. One open PR blocks Done.
• Team automation for “On PR or commit merge” is set to No action or points at a deleted status.
• Branch-specific rules override the default for that target branch (for example staging → In QA, and you expected Done on staging).

Fix: open the team’s Pull request and commit automations. Confirm the merge target status. If you squash-merged a branch that collected several earlier PRs, Linear will not auto-detect issue IDs from those earlier PRs – re-mention the IDs in the final PR title or description.

3. Autoclose fires at the wrong time

Symptom: issue flips to Done when the PR hits staging, or when a draft PR opens, or when someone pushes a commit to a feature branch.

Usual causes:

• Default automation moves to In Progress on PR open and Done on merge – including merges to non-production branches if you didn’t add branch rules.
• Commit linking is on, and a commit with a closing magic word reached the default branch earlier than you expected.
• Draft vs ready: configure the “draft” and “opened” states separately if your team uses draft PRs heavily.

Fix: add branch-specific rules on the target branch (main → Done, staging → In QA, or “no action”). Linear applies these to target branches only (the branch you merge into), not source branches. Regex works (^fea/.*).

Also know: canceling a Linear issue (or marking it duplicate) closes open GitHub PRs linked with a Closes/Contributes relationship. Completing an issue does not close PRs. If your merge queue closes PRs without a real merge, add the externally-merged label before close so Linear treats it as merged.

4. Status updates stopped syncing

Symptom: it worked last month; PRs still link, but status never moves.

Usual causes:

• Someone renamed workflow states in Linear and the automation still points at the old name.
• “Ready for merge” never fires (see next section), so the chain looks stuck one step early.
• GitHub Issues Sync (the separate two-way issue mirror) is what broke, not PR linking. Those are different features on the same settings page.

Fix for PR automation: re-save the team’s PR automation mapping. Fix for Issues Sync: check the sync banner on the Linear issue – Linear surfaces sync errors there. Issues Sync only covers newly created issues going forward; historical issues need the importer. Custom GitHub Project statuses do not sync.

5. “Ready for merge” never fires

Linear is explicit: Ready for merge needs GitHub to report a stable/mergeable PR. If any check fails (including non-required checks), GitHub reports unstable and the automation will not trigger. Also: without branch protection (required review or required check), a PR is always mergeable, and Ready for merge will not behave the way you expect unless a “review request or activity” automation is also configured.

Fix: turn on a required status check or required review on the protected branch, and keep failing optional checks from blocking you (or fix them). Then re-test with a PR that is actually green.

6. The integration died after a repo or org change

Symptom: everything was fine until someone moved the repo to a new org, renamed the org, or rotated who owns the GitHub App install.

Rules that bite:

• A GitHub App can be installed once per GitHub organization. That means one Linear workspace per GitHub org. You cannot point two Linear workspaces at the same org.
• One personal GitHub account can connect to one Linear workspace. If a contractor already connected their GitHub user elsewhere, ask someone else to own the org install.
• Moving a repo to a new org requires installing the app on the destination org and selecting that repo again.
• For GitHub Enterprise Cloud with an IP allow list, enable “IP allow list configuration for installed GitHub Apps” or allow Linear’s published IPs (listed in the docs).
• GitHub Enterprise Server has a separate app and no GitHub Issues Sync / commit linking parity – see Linear’s comparison table in the same doc.

Official reset path: disconnect the integration from GitHub → open https://linear.app/reset in the browser → reconnect in Linear settings.

Prevention: settings worth changing from default

• Turn on personal GitHub connections for every eng as part of onboarding.
• Standardize on Copy git branch name so IDs always land in the branch.
• Prefer closing magic words in the PR description template, not ad-hoc comments.
• Set branch rules for main vs staging on day one.
• Keep Issues Sync off unless you have a concrete intake repo. PR linking alone is enough for most product teams.
• Document the skip/ignore pattern for dependabot-style branches that happen to include an ID-like string.

If you’re still choosing whether Linear should own the backlog at all, start with the comparison, the Cycles guide, and Linear pricing. For Slack intake that feeds the same teams, see Linear Asks.

FAQ

Why does Linear show Connected but PRs still aren’t linking?

Connected means the OAuth handshake worked. Linking still needs a selected repo, a personal account connection, and an exact issue ID in the branch name, PR title, or a magic word in the description.

Does merging a PR always close the linked issue?

Only if you used a closing magic word (or the ID-in-title/branch path with merge automation enabled) and every linked PR has reached the merge state your team configured. Non-closing words and multi-PR issues are the usual surprises.

Can I link a Linear issue to a PR without touching the branch name?

Yes. Put the issue ID in the PR title, or use a magic word + ID in the PR description. Edit an already-open PR to add it.

Why did the integration break after we moved repos to a new organization?

The GitHub App install is per organization. Install Linear on the new org, select the repos, and have people reconnect personal accounts if needed. Then use the disconnect → reset → reconnect path if webhooks still look stale.

Behavior checked against linear.app/docs/github on October 9, 2026.

Sponsored

Related guides

Jira
The Ultimate Guide to Jira in 2026: Strengths, Limits, Pricing and Fit

ClickUp
ClickUp vs Basecamp 2026: Which Is Better for Small Teams and Agencies?

Jira
Why Your Jira Velocity Chart Shows Wrong Numbers (6 Fixes)