Linear-GitHub Sync Broken? Fix Every Failure Mode

Most Linear-GitHub sync failures come down to three things: the PR is missing a valid issue reference (wrong branch name or magic word), the team’s pull request automation is configured for a status your workflow doesn’t use, or the GitHub App installation lost permissions after a repo moved orgs or a personal account was revoked. Check Settings → Integrations → GitHub first — a green “Connected” badge only confirms OAuth succeeded, not that webhooks are actually delivering.

Table of Contents

• PRs aren’t linking to issues
• Issues don’t close when the PR merges
• Autoclose fires at the wrong time (merge vs. release)
• Status updates stopped syncing
• The integration disconnected after a repo or org change
• Prevention: settings worth changing from default
• FAQ

PRs aren’t linking to issues

You open a PR, merge it, and the Linear issue never even shows the attachment. No error, no notification — it just doesn’t happen. This is almost always a matching failure, not a connection failure.

Linear links a PR to an issue three ways: the issue ID appears in the branch name, the issue ID appears in the PR title, or a magic word plus the issue ID appears in the PR description. That last part trips people up constantly — magic words only work in the description or title. Put Fixes ENG-142 in a PR comment and nothing happens, because comments aren’t parsed for linking.

1. Open the PR and check the branch name or title for the exact team key, e.g. ENG-142. Confirm the key against Settings → Teams → [Team Name] → Identifier — it’s case-sensitive, so eng-142 will not match ENG-142.
2. If the branch name doesn’t carry an ID (common with auto-generated branches from a bot or a CI pipeline), add a magic word plus the issue ID directly into the PR description, not a comment: Fixes ENG-142.
3. Save the PR description. Linking happens after the save, not instantly on page load — give it a few seconds and refresh the Linear issue.
4. If you’re linking multiple issues to one PR, separate them after the magic word: Fixes ENG-142, DES-8 and ENG-201.
5. If you squash-merged several PRs into a single branch before opening the PR that ships them, Linear will not auto-detect the issues that were linked on the original PRs. You have to relink by adding the IDs to the new PR’s title or description manually.

One more thing worth checking: if your branch name includes an issue ID but you deliberately don’t want that PR linked (a hotfix branch that happens to reuse an old ticket’s key, for example), manually unlinking in Linear won’t stick. The link reappears the moment you push a new commit. Add skip ENG-142 or ignore ENG-142 to the PR description instead — that’s the only way to make it permanent.

Issues don’t close when the PR merges

The PR is linked — you can see the attachment on the issue — but merging it doesn’t move the status to Done. This usually means the PR was opened with a non-closing magic word, or no magic word at all and the branch-name link alone isn’t enough to trigger the merge automation in your team’s workflow config.

Linear splits magic words into two categories, and the difference matters:

• Closing words — close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, complete, completes, implement, implements, and a few tense variants of each. These move the issue to In Progress when the branch is pushed and to Done when the PR merges to the default branch.
• Non-closing words — ref, refs, references, part of, related to, relates to, contributes to, toward, towards. These link the PR and still move the issue through your configured pre-merge states, but they will never auto-close it on merge. If your team standardized on Related to ENG-142 instead of Fixes ENG-142, that’s why nothing closes.

1. Open the merged PR and reread the description. If it uses a non-closing word, that’s your answer — the PR is intentionally not wired to close the issue.
2. Check Settings → Team → Workflows & automations → Pull request and commit automations for the specific team the issue belongs to. This setting is per-team, not workspace-wide, so a fix on one team’s config does nothing for another team’s repo.
3. Confirm the destination status configured for “On PR or commit merge” is actually a status your team uses. If someone remapped it to a status that got renamed or archived, the automation has nowhere to send the issue and silently does nothing.
4. If you use a custom merge queue that merges the code and then closes the PR programmatically (rather than GitHub’s native merge button), you must apply the externally-merged label to the PR before it closes. Without that label, Linear sees a closed-not-merged PR and won’t treat it as a completed merge.
5. Re-test with a disposable branch using a known closing word, e.g. fix ENG-1 in the description, to confirm the automation path itself works before troubleshooting further.

Autoclose fires at the wrong time (merge vs. release)

This is the single most common expectation mismatch teams report. Someone expects an issue to close when a deployment goes out — when a GitHub release is published — but the issue closes the moment the PR merges to main, days or weeks before that code actually ships to production.

That’s not a bug. Linear’s core GitHub integration was built around merge events, not release events. The default automation, configured under Settings → Team → Workflows & automations → Pull request and commit automations, moves issues to In Progress on PR open and to Done on PR merge. There’s no toggle in the core integration that says “wait for a GitHub release instead of a merge” — merge is the trigger point, full stop.

If your team ships on a trunk-based model where merge and deploy happen close together, this is invisible. If you run a staging branch, a release train, or batch deployments, it creates a real gap between “Linear says Done” and “this is actually live.”

1. Use branch-specific rules instead of relying on the single default rule. In the same Pull request and commit automations settings, you can configure different destination statuses per target branch — merges to staging can move issues to “In QA” while merges to main move them to “Deployed,” rather than collapsing everything into one “Done” state at merge time.
2. If you need issues tied to an actual deployment or release artifact rather than a merge event, that’s a separate Linear feature called Releases, driven by the linear-release-action GitHub Action in CI. It scans commits for issue identifiers and creates or updates a Linear release record when your pipeline runs — this is the mechanism that actually understands “shipped,” not the PR-merge automation.
3. Set expectations with the team explicitly: merge-based automation tells you code is in the codebase, not that it’s in front of users. If leadership is reading “Done” as “live,” that’s a workflow-status naming problem worth fixing separately — consider a distinct “Merged” status ahead of “Deployed” so the two events don’t collapse into one label.

Status updates stopped syncing

Everything worked for weeks, then one day PR review comments and merge events stop moving issues at all — but the PR attachment is still visible on the issue, so it looks connected. This is almost always a webhook delivery problem, a branch protection gap, or an unmet check requirement, not a broken link.

1. Go to Settings → Integrations → GitHub in Linear and check the connection status. If it shows an error banner rather than a clean “Connected,” start there — it usually names the specific failure.
2. If Linear looks fine, check GitHub’s side: as an org owner, go to github.com/organizations/YOUR-ORG/settings/installations, open the Linear app, and look for a permissions-request banner. GitHub does not silently upgrade an app’s permissions when new features roll out — if Linear ever needs an additional scope, it sits there unapproved until someone with org owner access clicks through it.
3. If you’re troubleshooting the “Ready for merge” status specifically and it never fires, this one has a well-documented cause: it requires either a required review or a required status check configured on the branch. Without branch protection rules in place, GitHub treats every PR as always mergeable and Linear has no signal to distinguish “opened” from “ready.”
4. As a clean reset, disconnect the integration from GitHub’s side first, then go to linear.app/reset to clear Linear’s local cache, then reconnect from Linear’s integration settings. This is Linear’s own documented fix for an integration that’s gotten out of sync, and it resolves the majority of “it just stopped” reports without needing to touch webhook configuration manually.
5. Reinstalling does not backfill history. Once reconnected, only new PR and commit events create links — issues that lost their sync while the integration was broken will not retroactively pick up the PRs that merged during the outage. You’ll need to relink those manually by editing the PR title or description.

The integration disconnected after a repo or org change

A repo got transferred to a new GitHub organization, a company got acquired, or someone consolidated three GitHub orgs into one — and the Linear integration that worked fine yesterday now links nothing.

The root cause is almost always permission scope. Linear’s GitHub App is installed against a specific organization (or specific repositories within it if you used repo-level scope instead of org-level). When a repository moves to a different org, the original installation has no authority over it — GitHub doesn’t carry app installations across an org boundary automatically. It also matters who did the original install: an org-level connection requires a GitHub organization owner, while a repository-level connection can be set up by a repo admin, and the two aren’t interchangeable if the repo relocates.

1. Confirm which org currently owns the repository in question — check the repo URL directly rather than assuming, since transfers don’t always get communicated to the whole team.
2. In GitHub, go to github.com/organizations/NEW-ORG/settings/installations and check whether the Linear GitHub App is installed there at all. If the repo moved to an org where Linear was never installed, this is your answer — the app simply isn’t authorized on that org yet.
3. Have a GitHub organization owner (not just an admin) install the Linear GitHub App on the new org from Settings → Integrations → GitHub in Linear, then explicitly add the relocated repository to the app’s repository access list.
4. Remember GitHub’s own constraint here: a GitHub organization can only be connected to one Linear workspace. If the repo moved into an org that’s already linked to a different Linear workspace than yours, you cannot also connect it to your team’s workspace — that’s a hard platform limit, not a configuration bug.
5. If someone originally connected the integration using their personal GitHub account rather than through an org owner’s credentials, and that person later left or lost repo access, the whole integration can silently die for everyone else. Re-run the installation as a current org owner to remove that single point of failure.

Prevention: settings worth changing from default

A few defaults are fine for a five-person team and actively misleading once you’re running multiple teams or a staged release process. Worth revisiting before they cause a support ticket:

FAQ

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

A “Connected” status only confirms the OAuth handshake succeeded — it says nothing about whether your branch names or PR descriptions actually match a valid issue ID. Check the team key under Settings → Teams for an exact, case-sensitive match, and confirm any magic word sits in the PR description, not a comment.

Does merging a PR always close the linked issue?

No. It only closes the issue if the PR used a closing magic word (fix, fixes, resolve, resolves, close, closes, and their variants) or if your team’s Pull request and commit automations are configured to move issues to a closed status on merge. Non-closing words like “relates to” link the PR without ever auto-closing anything.

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

Yes. Put a magic word plus the issue ID directly in the PR title or description — for example Fixes ENG-142. This works even if the branch was auto-generated by a bot with no issue reference in its name, as long as the text is in the title or description and not buried in a later comment.

Why did my Linear-GitHub integration break after we moved repos to a new organization?

GitHub App installations are scoped to a specific organization and don’t transfer automatically when a repository moves. An org owner on the new organization needs to install the Linear GitHub App there and grant it access to the relocated repository — the old installation on the previous org has no authority over repos that have left it.

For the underlying mechanics of how PR events map to issue states, see Linear’s own GitHub integration documentation and the linear-release-action reference for teams that need deployment-triggered automation instead of merge-triggered automation. If you’re deciding whether GitHub Issues or Linear should own your tracking in the first place, our Linear vs GitHub Issues comparison covers that tradeoff in more depth. And if the sync itself is fine but your cycle rollovers or velocity data look off, that’s covered separately in our Linear cycles and sprint planning guide, along with a broader look at the platform in our Linear review.

Sponsored