Sync Issues To Dispatcher

Push GitHub issues into Linear with intelligent field mapping, label translation, and priority normalization for seamless cross-platform project management.

When to Use This Command

Run this command when...

• You have a backlog of GitHub issues that need to appear in Linear for sprint planning and team assignment
• New issues arrive in GitHub from external contributors and you want them automatically dispatched to the correct Linear team
• You are migrating from a GitHub-only workflow to a hybrid GitHub-Linear workflow and need initial bulk import

Avoid this command when...

• You need bidirectional sync where Linear changes flow back to GitHub (use a bidirectional sync configuration instead)
• The issues contain security vulnerability reports that should not leave the GitHub security advisory system

Quick Start

Copy
# .github-linear-sync.yaml
source: github
target: linear
repository: myorg/myrepo
linear_team: "Engineering"
field_mapping:
  title: title
  body: description
  labels: labels
  milestone: project
priority_map:
  critical: 1
  high: 2
  medium: 3
  low: 4

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

Expected output:
Repository: myorg/myrepo
Open issues found: 23
Mapping fields: title, body, labels, milestone -> project
Priority normalization: critical->1, high->2, medium->3, low->4
Synced: 23/23 issues dispatched to Linear (Engineering)
  - Created: 19 new Linear issues
  - Updated: 4 existing (matched by title)
  - Skipped: 0
Link references saved to .sync-state.json

Core Concepts

Concept	Description
Field Mapping	Translates GitHub issue fields (title, body, labels) into their Linear equivalents
Priority Normalization	Converts GitHub label-based priority into Linear's numeric priority scale (1-4)
Label Translation	Maps GitHub labels to Linear labels, creating missing labels automatically
Deduplication	Matches existing Linear issues by title or external ID to prevent duplicate creation
Dispatch Routing	Assigns issues to the correct Linear team and project based on configurable rules

GitHub Issues          Mapper             Linear
[issue #1] --title--> [Field Map] --title-------> [Issue LIN-1]
           --labels-> [Priority]  --priority:2-->
           --body---> [Sanitize]  --description->
           --milestone> [Route]   --project-----> [Project: Q1]

Configuration

Parameter	Type	Default	Description	Example
repository	string	current repo	GitHub repository to sync from	myorg/myrepo
linear_team	string	required	Target Linear team name	Engineering
field_mapping	object	default map	GitHub-to-Linear field translation	See Quick Start
priority_map	object	label-based	Label-to-priority number mapping	{ "critical": 1 }
filter_labels	array	[]	Only sync issues with these labels	["sync-to-linear"]

Best Practices

1. Use a sync label to control which issues dispatch -- Add a sync-to-linear label to GitHub issues that should transfer, preventing noise from every issue flooding Linear.
2. Map milestones to Linear projects -- GitHub milestones align well with Linear projects; set up the mapping so sprint planning in Linear reflects GitHub release targets.
3. Run initial bulk sync during off-hours -- The first sync of a large backlog generates many API calls; schedule it when rate limits are least contested.
4. Verify field mapping with a dry run -- Use --dry-run to preview how fields translate before creating issues in Linear to avoid cleanup work.
5. Store sync state in the repository -- Commit .sync-state.json so that subsequent syncs correctly identify previously dispatched issues and avoid duplicates.

Common Issues

1. Duplicate issues created in Linear -- The deduplication matcher relies on consistent titles. If GitHub issue titles were edited after initial sync, the matcher cannot find the existing Linear issue. Re-run with --force-match-by-id to use the stored mapping.
2. Labels not appearing in Linear -- Linear label creation requires team-level permissions. Verify that the API token has admin access to the target team.
3. Rate limit exceeded during bulk sync -- GitHub's API allows 5,000 requests per hour. For repositories with hundreds of issues, enable pagination batching and add --rate-limit-delay 500 to space requests.