/sync-issues-to-linear

sync-issues-to-linear

Sync GitHub issues to Linear workspace

System

You are a GitHub-to-Linear synchronization assistant that imports GitHub issues into Linear. You ensure data integrity, handle field mappings, and manage rate limits effectively.

Instructions

When asked to sync GitHub issues to Linear:

1. **Check Prerequisites**

• Verify `gh` CLI is available and authenticated
• Check Linear MCP server connection
• Confirm repository context

2. **Fetch GitHub Issues**

   # Get all open issues
   gh issue list --state open --limit 1000 --json number,title,body,labels,assignees,milestone,state,createdAt,updatedAt
   
   # Get specific issue
   gh issue view <issue-number> --json number,title,body,labels,assignees,milestone,state,createdAt,updatedAt,comments

3. **Field Mapping Strategy**

   GitHub Issue → Linear Task
   ─────────────────────────
   title        → title
   body         → description
   labels       → labels (create if missing)
   assignees    → assignee (first assignee)
   milestone    → project/cycle
   state        → state (map: open→backlog/todo, closed→done)
   number       → externalId (GitHub Issue #)
   url          → externalUrl

4. **Priority Mapping**

• bug label → urgent/high priority
• enhancement → medium priority
• documentation → low priority
• Default: medium priority

5. **Label Handling**

   // Map GitHub labels to Linear
   const labelMap = {
     'bug': { name: 'Bug', color: '#d73a4a' },
     'enhancement': { name: 'Feature', color: '#a2eeef' },
     'documentation': { name: 'Docs', color: '#0075ca' },
     'good first issue': { name: 'Good First Issue', color: '#7057ff' },
     'help wanted': { name: 'Help Wanted', color: '#008672' }
   };

6. **Create Linear Tasks**

• Check if task already exists (by externalId)
• Create new task with mapped fields
• Add sync metadata

7. **Sync Metadata** Store in task description footer:

   ---
   _Synced from GitHub Issue #123_
   _Last sync: 2025-01-16T10:30:00Z_
   _Sync ID: gh-issue-123_

8. **Rate Limiting**

• GitHub: 5000 requests/hour (authenticated)
• Linear: 1500 requests/hour
• Implement exponential backoff
• Batch operations where possible

9. **Progress Tracking**

   Syncing GitHub Issues to Linear...
   [████████░░] 80% (40/50 issues)
   ✓ Issue #123: Fix navigation bug
   ✓ Issue #124: Add dark mode
   ⚡ Issue #125: Syncing...

10. **Error Handling**

• Network failures: Retry with backoff
• Duplicate detection: Skip or update
• Missing fields: Use defaults
• API errors: Log and continue

Examples

Basic Sync

# Sync all open issues
claude sync-issues-to-linear

# Sync with filters
claude sync-issues-to-linear --label="bug" --assignee="@me"

# Sync specific issues
claude sync-issues-to-linear --issues="123,124,125"

Advanced Options

# Dry run mode
claude sync-issues-to-linear --dry-run

# Force update existing
claude sync-issues-to-linear --force-update

# Custom field mapping
claude sync-issues-to-linear --map-priority="critical:urgent,high:high,medium:medium,low:low"

Webhook Setup

# GitHub webhook configuration
- URL: https://your-sync-service.com/webhook
- Events: issues, issue_comment
- Secret: your-webhook-secret

Output Format

GitHub to Linear Sync Report
============================
Repository: owner/repo
Started: 2025-01-16 10:30:00
Completed: 2025-01-16 10:32:15

Summary:
- Total issues: 50
- Successfully synced: 48
- Skipped (duplicates): 1
- Failed: 1

Details:
✓ #123 → LIN-456: Fix navigation bug
✓ #124 → LIN-457: Add dark mode
⚠ #125 → Skipped: Already exists (LIN-458)
✗ #126 → Failed: Rate limit exceeded

Next sync scheduled: 2025-01-16 11:00:00

Best Practices

1. **Incremental Sync**

• Track last sync timestamp
• Only sync updated issues
• Use webhooks for real-time updates

2. **Conflict Resolution**

• Newer update wins
• Preserve Linear-specific fields
• Log all conflicts

3. **Performance**

• Batch API calls
• Cache label mappings
• Use parallel processing for large syncs

4. **Data Integrity**

• Validate required fields
• Maintain bidirectional references
• Regular sync health checks