Sync Pr Fast

Link GitHub pull requests to Linear tasks with automatic status transitions, branch-name detection, and comprehensive workflow integration.

When to Use This Command

Run this command when...

• A pull request has been opened and you want it automatically linked to the corresponding Linear task based on branch name or PR body references
• You need PR merge events to transition Linear tasks to "Done" or "In Review" status without manual updates
• You want a quick audit of all PRs and their linked Linear tasks to verify nothing was missed

Avoid this command when...

• You need to sync entire GitHub issues (not PRs) to Linear (use Sync Issues To Dispatcher instead)
• The PR has no corresponding Linear task and you want to create one from scratch (use issue dispatch commands instead)

Quick Start

Copy
# .pr-sync.yaml
repository: myorg/myrepo
linear_team: "Engineering"
branch_pattern: "^(feat|fix|chore)/([A-Z]+-[0-9]+)"
status_transitions:
  pr_opened: "In Review"
  pr_merged: "Done"
  pr_closed: "Cancelled"

Copy
claude -p "Link PR #142 to its Linear task and update the task status to In Review"

Expected output:
PR #142: feat/ENG-347-add-auth-middleware
Branch pattern match: ENG-347
Linear task found: ENG-347 "Add authentication middleware"
Status transition: Backlog -> In Review
PR link added to Linear task: https://github.com/myorg/myrepo/pull/142
Linear link added to PR body: https://linear.app/myorg/issue/ENG-347
Sync complete in 1.8s

Core Concepts

Concept	Description
Branch Detection	Extracts Linear task IDs from branch names using configurable regex patterns
Status Transition	Maps PR lifecycle events (opened, merged, closed) to Linear workflow state changes
Bidirectional Linking	Adds cross-reference URLs in both the PR description and Linear task comments
PR Body Scanning	Falls back to scanning PR title and body for task ID references if branch name has no match
Bulk Audit	Scans all open PRs to identify any missing Linear task links

PR Opened --------> Branch Parse --------> Linear Lookup
  |                  "feat/ENG-347-..."      |
  |                       |                  v
  |                    ENG-347          [Task Found]
  |                                         |
  v                                         v
Add Linear link              Status -> "In Review"
to PR body                   Add PR link to task

Configuration

Parameter	Type	Default	Description	Example
branch_pattern	string	([A-Z]+-[0-9]+)	Regex to extract task ID from branch name	^feat/([A-Z]+-\\d+)
status_transitions	object	default map	PR event to Linear status mapping	See Quick Start
auto_link	boolean	true	Automatically add cross-reference links	false
scan_body	boolean	true	Search PR body for task IDs if branch has none	true
repository	string	current repo	GitHub repository to monitor	myorg/myrepo

Best Practices

1. Enforce branch naming conventions -- The entire system depends on extractable task IDs. Use branch protection rules or commit hooks to enforce the pattern.
2. Add both forward and backward links -- Cross-references in both systems let reviewers jump between code review and task context instantly.
3. Map all terminal PR states -- Include both pr_merged and pr_closed transitions so that abandoned PRs also update the Linear task status.
4. Run bulk audit weekly -- Scan all open PRs for missing links to catch manually created branches that skipped the naming convention.
5. Use draft PR status -- Map draft PRs to a "Started" status in Linear so the team sees work has begun without it being "In Review."

Common Issues

1. Branch name does not match pattern -- The regex may be too strict. Test against actual branch names with a regex tool. Common miss: forgetting to account for nested prefixes like feature/team/ENG-347.
2. Linear task not found for extracted ID -- The task may be in a different Linear team than the configured one. Add search_all_teams: true or list multiple teams.
3. Status transition rejected by Linear -- Linear workflow rules may not allow the transition (e.g., jumping from "Done" back to "In Review"). Configure your workflow to permit all transitions used by PR sync.