Linear Not Syncing with GitHub: How to Fix the 5 Most Common Issues (2026)

Why a Broken Linear–GitHub Sync Costs More Than You Think

A misconfigured integration is not a minor inconvenience — it is a compounding tax on every engineer on your team. When Linear issues do not auto-transition on PR events, status updates get missed, cycle velocity metrics become meaningless, and developers spend 10–15 minutes per PR manually updating tickets that the integration should handle automatically. Across a 10-person engineering team shipping 20 PRs per week, that is 2,000–3,000 minutes of avoidable overhead every month.

The stakes rose significantly in April 2026 when Linear shipped AI Agents as a native feature — bundled into Plus and Enterprise plans with no metered token charges. These agents can automatically open and close pull requests, write status comments on issues, and reorder cycle priorities based on PR activity. But every one of those capabilities depends entirely on the GitHub integration being correctly scoped. A sync that “mostly works” for basic webhook events will completely fail for AI Agent workflows, and the failure is silent: no error surface, no alert, just an agent that never fires.

This guide covers the five issues responsible for the overwhelming majority of broken Linear–GitHub sync reports in 2026, in order of how commonly they appear in production workspaces.

Issue 1: OAuth App Installed in User Mode Instead of App Installation Mode

Symptom: GitHub events appear in the Linear audit log, but issue status does not change when PRs are opened or merged. AI Agent actions targeting GitHub return a 403 Resource Not Accessible by Integration error in the agent activity log.

Root cause: Linear’s GitHub OAuth flow has two distinct installation modes. To install it as a GitHub App (organization-level, persistent, not tied to any individual’s account), the authorization URL must include actor=app as a query parameter. This single missing parameter is the most common root cause of broken agent-to-GitHub workflows.

How to fix it:

1. Navigate to Settings > Integrations > GitHub in your Linear workspace.
2. Click Disconnect to remove the existing user-mode installation. Confirm when prompted.
3. Do not click the standard Connect GitHub button. Instead, manually construct the authorization URL: https://linear.app/oauth/github?actor=app
4. Navigate to that URL in your browser. You will see an “Install GitHub App” dialog.
5. Select All repositories or select the specific repositories this Linear workspace should monitor. Click Install & Authorize.
6. Return to Settings > Integrations > GitHub and confirm the connection status shows Connected as GitHub App — not “Connected as [your GitHub username]”.
7. Test by opening a draft PR with a branch name that includes a valid Linear issue identifier (e.g., feature/ENG-142-payment-refactor). The linked issue should appear in the PR sidebar within 30 seconds.

Issue 2: Missing Webhook Events and Agent Session Scope

Symptom: Basic PR linking works (issue ID appears in the PR), but automated status transitions do not fire, and Linear AI Agents with GitHub actions produce no output.

Root cause: Linear’s GitHub integration requires two categories of webhook subscriptions: standard repository webhook events (push, pull_request, pull_request_review) and — new as of the AI Agents rollout — Agent session events. The Agent session events subscription is not enabled by default on integrations installed before April 2026.

How to fix it:

1. Go to Settings > Integrations > GitHub in Linear.
2. Click Configure next to your connected GitHub App installation.
3. Under the Webhook Events section, confirm all of the following are checked: Push, Pull request, Pull request review, Pull request review comment, Create, and Delete.
4. Scroll to the Agent & Automation Events section. Enable Agent session events. This toggle is separate from the webhook events list and is easy to miss.
5. Click Save configuration.
6. Navigate to your GitHub organization settings and verify recent webhook deliveries show 200 OK responses.
7. If any recent webhook deliveries show 422 Unprocessable Entity, click Redeliver on a failed event to force replay.

Issue 3: Branch Naming Convention Mismatch

Symptom: PRs open and merge without triggering any issue status change in Linear. The integration appears connected and webhook deliveries return 200, but no issues link to any PRs.

Root cause: Linear identifies which issue a PR belongs to by parsing the branch name or PR title for an issue identifier matching the pattern [TEAM_KEY]-[NUMBER]. The team key is case-sensitive and must exactly match the identifier displayed in Linear.

How to fix it:

1. In Linear, go to Settings > Teams and note the exact team key (identifier) shown under each team name.
2. Verify a branch name manually: create a test branch named feature/ENG-1-test-sync and open a draft PR. The linked Linear issue should appear within 60 seconds.
3. If no link appears, check your team key under Settings > Teams > [Team Name] > Identifier.
4. Update your team’s branch naming convention documentation and any git hooks that auto-generate branch names.
5. For PR titles, the same parsing logic applies. The team key matching is case-sensitive.

Linear also supports linking via magic words in PR descriptions. Including Closes ENG-142, Fixes ENG-142, or Resolves ENG-142 in the PR body will link the PR and auto-close the issue on merge.

Issue 4: User-Level vs. Organization-Level App Installation

Symptom: Sync works intermittently — it functions for one engineer but not others, or it stopped working after a specific team member left the company or had their GitHub access revoked.

Root cause: When a team member installs the Linear GitHub App using their personal GitHub account rather than an organization owner account, the app installation is scoped to that individual’s access. If the installing user loses access to the repository, the entire integration breaks for everyone on that workspace.

How to fix it:

1. In GitHub, navigate to github.com/organizations/YOUR-ORG/settings/installations. Log in as a GitHub organization owner.
2. Locate the Linear app entry. If it is listed with a personal account avatar rather than your organization logo, it was installed at the user level.
3. Click Configure then Uninstall to remove the user-level installation.
4. In Linear, go to Settings > Integrations > GitHub and click Disconnect to clear the stale connection reference.
5. While still logged into GitHub as an org owner, re-authorize using the app installation URL: https://linear.app/oauth/github?actor=app.
6. Confirm the installation appears under your organization’s installed apps (with the org logo) in GitHub settings.

Issue 5: Insufficient Repository Permissions on the GitHub App

Symptom: The integration connects successfully and some events fire, but specific actions fail — most commonly, Linear AI Agents cannot open PRs, cannot post comments, or cannot update PR labels. The agent activity log shows GitHub API Error: 403 – Forbidden on specific action types.

Root cause: Organizations that installed the integration before AI Agents were released (pre-April 2026) may not have granted the additional permissions that agent workflows require. GitHub does not automatically upgrade permission grants when an app requests new scopes.

How to fix it:

1. Navigate to github.com/organizations/YOUR-ORG/settings/installations as an org owner.
2. Click Configure next to the Linear app. If there is a yellow banner reading “Linear is requesting updated permissions”, this is your root cause. Click Review request.
3. Review the permission diff. For AI Agent support, Linear requires: Read and write access to Pull requests, Issues, Contents, and Checks.
4. Click Accept new permissions. The yellow banner will disappear.
5. Back in Linear, navigate to Settings > Integrations > GitHub > Configure and click Verify permissions.
6. Trigger a test agent action: from any Linear issue, open the agent panel and instruct it to “create a draft PR for this issue.” If permissions are correct, a draft PR should appear in GitHub within 10–15 seconds.

Enabling Linear AI Agents After Fixing the Integration

Once the underlying sync issues are resolved, many teams discover their AI Agent configuration also needs attention. Linear AI Agents (available on Plus and Enterprise plans from April 2026, with no per-token metering) can handle four categories of GitHub-related work automatically:

• PR lifecycle management: automatically opening draft PRs when an issue enters In Progress, converting drafts to ready-for-review when the issue reaches In Review, and closing PRs when issues are cancelled
• Status commenting: writing structured status updates on GitHub PRs based on Linear issue state changes
• Cycle reordering: adjusting issue priority within a cycle based on PR review age and blocking dependencies detected from GitHub check runs
• Label synchronization: mirroring Linear issue labels to GitHub PR labels for filtering and reporting

To enable agent workflows after fixing the integration:

1. Confirm your workspace is on a Plus or Enterprise plan: Settings > Workspace > Plan.
2. Navigate to Settings > Agents and enable the GitHub Agent toggle.
3. Configure agent trigger conditions under Settings > Agents > GitHub Agent > Triggers. At minimum, enable On issue status change and On PR merge.
4. Ensure the Agent session events webhook scope from Issue 2 above is enabled — agent triggers will not fire without it.
5. Test agent functionality by manually transitioning a linked issue to In Progress and confirming a draft PR appears in GitHub within 30 seconds.

FAQ