Sync Linear To Dispatcher

Push Linear issues and tasks back into GitHub as issues or project cards with status mapping, assignee resolution, and cross-reference linking.

When to Use This Command

Run this command when...

• Your team plans work in Linear but needs visibility in GitHub for open-source contributors or external stakeholders
• You want Linear task status changes to automatically reflect as GitHub issue state updates (open/closed)
• You are running a hybrid workflow where some teams use GitHub Projects and others use Linear, requiring bidirectional visibility

Avoid this command when...

• All contributors already have Linear access and there is no need for GitHub issue mirroring
• You only need to sync in the GitHub-to-Linear direction (use Sync Issues To Dispatcher instead)

Quick Start

Copy
# .linear-github-sync.yaml
source: linear
target: github
linear_team: "Engineering"
repository: myorg/myrepo
status_mapping:
  "In Progress": open
  "Done": closed
  "Cancelled": closed
  "Backlog": open
assignee_map:
  "[email protected]": "github-username"

Copy
claude -p "Sync all active Linear issues from Engineering team to GitHub issues in myorg/myrepo"

Expected output:
Linear team: Engineering
Active issues found: 31
Status mapping: In Progress->open, Done->closed, Cancelled->closed
Assignee resolution: 8 Linear users mapped to GitHub accounts
Synced: 31/31 issues dispatched to GitHub
  - Created: 24 new GitHub issues
  - Updated: 7 existing (status changed)
  - Cross-references: 31 bidirectional links added

Core Concepts

Concept	Description
Status Mapping	Translates Linear workflow states into GitHub issue open/closed states
Assignee Resolution	Maps Linear user identities to GitHub usernames using a lookup table
Cross-Reference Links	Adds reciprocal links in both systems so either issue links to its counterpart
Selective Sync	Filters which Linear issues to sync based on team, project, status, or label criteria
State Reconciliation	Detects when GitHub issue state drifts from Linear and corrects it

Linear Issues         Mapper              GitHub
[LIN-42] --status--> [State Map] --open/closed-> [Issue #87]
         --assign--> [User Map]  --@github-user->
         --desc----> [Markdown]  --body--------->
         --link----> [X-Ref]     --"See LIN-42"->
                                      |
                        GitHub <------+------> Linear
                        (cross-reference links)

Configuration

Parameter	Type	Default	Description	Example
linear_team	string	required	Source Linear team name	Engineering
repository	string	required	Target GitHub repository	myorg/myrepo
status_mapping	object	default map	Linear status to GitHub state translation	See Quick Start
assignee_map	object	{}	Linear email to GitHub username mapping	{ "[email protected]": "ghuser" }
sync_labels	boolean	true	Sync Linear labels as GitHub labels	false

Best Practices

1. Maintain a complete assignee map -- Unmapped assignees result in unassigned GitHub issues, which reduces triage efficiency. Audit the map when team composition changes.
2. Use cross-reference links for traceability -- The bidirectional links let anyone navigate from a GitHub issue to its Linear source, preserving context across platforms.
3. Filter by Linear project or label -- Avoid syncing internal-only tasks (like internal tooling) to public GitHub repositories by applying project or label filters.
4. Run status reconciliation periodically -- If GitHub issues are manually closed without updating Linear, reconciliation corrects the drift before it causes confusion.
5. Document the status mapping for the team -- Post the status-to-state translation table in your project wiki so contributors understand what each GitHub state means in Linear terms.

Common Issues

1. GitHub issues created without assignees -- The assignee map is incomplete. Add missing mappings or enable auto_match_by_email to attempt automatic GitHub username lookup from email.
2. Cross-reference links point to wrong issues -- The link mapping file may be corrupted. Delete .sync-state.json and run a fresh sync with --rebuild-links to recreate all cross-references.
3. Closed Linear issues still show as open in GitHub -- The status mapping may not include all terminal states. Add all closed-equivalent Linear states (Done, Cancelled, Duplicate) to the mapping configuration.