GitHub-Linear Bidirectional Sync

Command

/sync-github-linear

Description

Establishes and maintains bidirectional synchronization between GitHub Issues and Linear tasks. When an issue is updated in either platform, the corresponding item in the other platform is updated to match. Supports status mapping, label sync, and assignee linking.

Behavior

1. Initial Setup -- Configures the mapping between GitHub repo and Linear team/project
2. Status Mapping -- Maps GitHub issue states and labels to Linear workflow states
3. Sync Operations:
   • Create: New GitHub issue creates a Linear task (and vice versa)
   • Status: Closing a GitHub issue moves the Linear task to "Done"
   • Labels: Maps GitHub labels to Linear labels
   • Assignees: Links GitHub usernames to Linear user accounts
   • Comments: Syncs comments bidirectionally with source attribution
4. Conflict Resolution -- Last-write-wins with configurable priority (Linear or GitHub as source of truth)

Output Format

Sync Configuration (.github/linear-sync.yml)

Copy
linear:
  team_key: "ENG"
  project: "Q1 Sprint"
  api_key_env: "LINEAR_API_KEY"

github:
  repo: "org/repo-name"
  token_env: "GITHUB_TOKEN"

status_mapping:
  github_to_linear:
    open: "In Progress"
    closed: "Done"
  labels_to_status:
    "in-review": "In Review"
    "blocked": "Blocked"
    "backlog": "Backlog"

label_mapping:
  "bug": "Bug"
  "feature": "Feature"
  "tech-debt": "Improvement"

assignee_mapping:
  github_username: "linear_display_name"

sync_options:
  direction: "bidirectional"  # or "github-to-linear" or "linear-to-github"
  conflict_resolution: "linear-wins"
  sync_comments: true
  sync_labels: true
  create_backlinks: true

Sync Report

Copy
## Sync Summary
| Direction | Created | Updated | Conflicts | Errors |
|-----------|---------|---------|-----------|--------|
| GitHub → Linear | 3 | 7 | 0 | 0 |
| Linear → GitHub | 1 | 4 | 1 | 0 |

### Conflicts Resolved
- ENG-142 / #87: Status conflict (Linear: "In Review", GitHub: "open") → Used Linear value

### Backlinks Created
- #91 → ENG-156: "Add user export feature"
- #92 → ENG-157: "Fix pagination on dashboard"

Examples

/sync-github-linear --setup                    # Initial configuration wizard
/sync-github-linear                            # Run sync with existing config
/sync-github-linear --dry-run                  # Preview changes without applying
/sync-github-linear --since "2025-03-01"       # Sync only recent changes
/sync-github-linear --issue ENG-142            # Sync a specific Linear issue