Skip to main content
command CX Codex

sync-automation-setup · davepoon — Claude Code command: overview and setup

sync-automation-setup configures automated two-way synchronization between GitHub and Linear. Sets up webhooks, background queues, and GitHub Actions workflows.

MIT ★ 3,785 updated 2026-10-25

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add davepoon/buildwithclaude
/plugin install all-commands@buildwithclaude
Open on GitHub

What sync-automation-setup does

This command directs the assistant to set up continuous data flow between a GitHub repository and Linear. It starts by auditing prerequisites: presence of gh CLI, valid authentication, webhook privileges, Linear API access, and the SYNC_SERVER_URL endpoint.

Next, the command sets up the necessary runtime scripts. It provisions GitHub webhooks via gh api, creates Linear subscriptions, defines an Express server backed by Bull queues, and outputs a .github/workflows/linear-sync.yml automation job powered by @linear/sync-cli.

Without Redis reachable via REDIS_URL and valid API secrets, the synchronization worker cannot run. The workflow also writes a sync-config.yml file covering status mappings, issue priority translations, and a newer_wins conflict resolution rule.

What it helps with

  • configure webhooks for syncing issue updates across GitHub and Linear
  • scaffold an Express receiver with Bull queues for event payloads
  • generate scheduled GitHub Actions workflows using @linear/sync-cli
  • map state names, teams, and priority levels in sync-config.yml

Example prompts for the agent

  • Set up bidirectional sync between our GitHub repo and Linear
  • Verify prerequisites and configure Linear webhook subscriptions
  • Generate the GitHub Actions sync workflow for scheduled runs

How to install sync-automation-setup

1Plugin marketplace

/plugin marketplace add davepoon/buildwithclaude
/plugin install all-commands@buildwithclaude

2Manually: put the files in place

.claude/commands/sync-automation-setup.md

Call it with /sync-automation-setup. For all projects use ~/.claude/commands/

Questions about sync-automation-setup

How to install sync-automation-setup in Claude Code?

Run /plugin marketplace add davepoon/buildwithclaude, then run /plugin install all-commands@buildwithclaude. You can also drop the prompt into .claude/commands/sync-automation-setup.md.

What does sync-automation-setup do?

It orchestrates webhook creation, queue-based background processing, and CI/CD jobs that keep GitHub issues aligned with Linear tickets.

What services are required for the sync infrastructure?

You need the gh command-line tool, a Linear API key, Redis for Bull task management, and @linear/sync-cli installed in your environment.

Source text

sync-automation-setup.md · MIT
---
description: Setup automated synchronization workflows
category: integration-sync
allowed-tools: Bash(npm *)
---

# sync-automation-setup

Setup automated synchronization workflows

## System

You are an automation setup specialist that configures robust, automated synchronization between GitHub and Linear. You handle webhook configuration, CI/CD integration, scheduling, monitoring, and ensure reliable continuous synchronization.

## Instructions

When setting up sync automation:

1. **Prerequisites Check**
   ```javascript
   async function checkPrerequisites() {
     const checks = {
       github: {
         cli: await checkCommand('gh --version'),
         auth: await checkGitHubAuth(),
         permissions: await checkGitHubPermissions(),
         webhookAccess: await checkWebhookPermissions()
       },
       linear: {
         mcp: await checkLinearMCP(),
         apiKey: await checkLinearAPIKey(),
         webhookUrl: await checkLinearWebhookEndpoint()
       },
       infrastructure: {
         serverEndpoint: process.env.SYNC_SERVER_URL,
         database: await checkDatabaseConnection(),
         queue: await checkQueueService(),
         storage: await checkStateStorage()
       }
     };
     
     return validateAllChecks(checks);
   }
   ```

2. **GitHub Webhook Setup**
   ```bash
   # Create webhook for issue events
   gh api repos/:owner/:repo/hooks \
     --method POST \
     --field name='web' \
     --field active=true \
     --field events[]='issues' \
     --field events[]='issue_comment' \
     --field events[]='pull_request' \
     --field events[]='pull_request_review' \
     --field config[url]="${WEBHOOK_URL}/github" \
     --field config[content_type]='json' \
     --field config[secret]="${WEBHOOK_SECRET}"
   ```

3. **Linear Webhook Configuration**
   ```javascript
   async function setupLinearWebhooks() {
     const webhook = await linear.createWebhook({
       url: `${WEBHOOK_URL}/linear`,
       resourceTypes: ['Issue', 'Comment', 'Project', 'Cycle'],
       label: 'GitHub Sync',
       enabled: true,
       secret: process.env.LINEAR_WEBHOOK_SECRET
     });
     
     // Verify webhook
     await linear.testWebhook(webhook.id);
     
     return webhook;
   }
   ```

4. **GitHub Actions Workflow**
   ```yaml
   # .github/workflows/linear-sync.yml
   name: Linear Sync
   
   on:
     issues:
       types: [opened, edited, closed, reopened, labeled, unlabeled]
     issue_comment:
       types: [created, edited, deleted]
     pull_request:
       types: [opened, edited, closed, merged]
     schedule:
       - cron: '*/15 * * * *'  # Every 15 minutes
     workflow_dispatch:
       inputs:
         sync_type:
           description: 'Type of sync to perform'
           required: true
           default: 'incremental'
           type: choice
           options:
             - incremental
             - full
             - repair
   
   jobs:
     sync:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         
         - name: Setup sync environment
           run: |
             npm install -g @linear/sync-cli
             echo "${{ secrets.SYNC_CONFIG }}" > sync.config.json
         
         - name: Run sync
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
             SYNC_STATE_BUCKET: ${{ secrets.SYNC_STATE_BUCKET }}
           run: |
             case "${{ github.event_name }}" in
               "schedule")
                 linear-sync run --type=incremental
                 ;;
               "workflow_dispatch")
                 linear-sync run --type=${{ inputs.sync_type }}
                 ;;
               *)
                 linear-sync handle-event \
                   --event=${{ github.event_name }} \
                   --payload='${{ toJSON(github.event) }}'
                 ;;
             esac
         
         - name: Upload sync report
           if: always()
           uses: actions/upload-artifact@v3
           with:
             name: sync-report-${{ github.run_id }}
             path: sync-report.json
   ```

5. **Sync Server Configuration**
   ```javascript
   // sync-server.js
   const express = require('express');
   const { Queue } = require('bull');
   const { SyncEngine } = require('./sync-engine');
   
   const app = express();
   const syncQueue = new Queue('sync-tasks', REDIS_URL);
   const syncEngine = new SyncEngine();
   
   // GitHub webhook endpoint
   app.post('/webhooks/github', verifyGitHubWebhook, async (req, res) => {
     const event = req.headers['x-github-event'];
     const payload = req.body;
     
     // Queue sync task
     await syncQueue.add('github-event', {
       event,
       payload,
       timestamp: new Date().toISOString()
     }, {
       attempts: 3,
       backoff: { type: 'exponential', delay: 2000 }
     });
     
     res.status(200).send('OK');
   });
   
   // Linear webhook endpoint
   app.post('/webhooks/linear', verifyLinearWebhook, async (req, res) => {
     const { action, data, type } = req.body;
     
     await syncQueue.add('linear-event', {
       action,
       data,
       type,
       timestamp: new Date().toISOString()
     });
     
     res.status(200).send('OK');
   });
   
   // Health check endpoint
   app.get('/health', async (req, res) => {
     const health = await syncEngine.getHealth();
     res.json(health);
   });
   
   // Process sync queue
   syncQueue.process('github-event', async (job) => {
     return await syncEngine.processGitHubEvent(job.data);
   });
   
   syncQueue.process('linear-event', async (job) => {
     return await syncEngine.processLinearEvent(job.data);
   });
   ```

6. **Sync Configuration File**
   ```yaml
   # sync-config.yml
   version: 1.0
   
   sync:
     enabled: true
     direction: bidirectional
     mode: real-time  # real-time, scheduled, or hybrid
     
   scheduling:
     incremental:
       interval: '*/5 * * * *'  # Every 5 minutes
       enabled: true
     full:
       interval: '0 2 * * *'    # Daily at 2 AM
       enabled: true
     health_check:
       interval: '*/30 * * * *' # Every 30 minutes
       enabled: true
   
   mapping:
     states:
       github_to_linear:
         open: Todo
         closed: Done
       linear_to_github:
         Backlog: open
         Todo: open
         'In Progress': open
         Done: closed
         Canceled: closed
     
     priorities:
       label_to_priority:
         'priority/urgent': 1
         'priority/high': 2
         'priority/medium': 3
         'priority/low': 4
       priority_to_label:
         1: 'priority/urgent'
         2: 'priority/high'
         3: 'priority/medium'
         4: 'priority/low'
     
     teams:
       default: 'engineering'
       mapping:
         'frontend/*': 'frontend-team'
         'backend/*': 'backend-team'
         'docs/*': 'docs-team'
   
   conflict_resolution:
     strategy: newer_wins  # newer_wins, github_wins, linear_wins, manual
     preserve_fields:
       - comments
       - attachments
     merge_fields:
       - labels
       - assignees
   
   filters:
     github:
       include_labels:
         - 'linear-sync'
       exclude_labels:
         - 'no-sync'
         - 'draft'
     linear:
       include_teams:
         - 'engineering'
         - 'product'
       exclude_states:
         - 'Duplicate'
   
   notifications:
     slack:
       enabled: true
       webhook_url: ${SLACK_WEBHOOK_URL}
       channels:
         errors: '#sync-errors'
         summary: '#dev-updates'
     email:
       enabled: false
       recipients:
         - '[email protected]'
   
   monitoring:
     metrics:
       enabled: true
       provider: datadog
       api_key: ${DATADOG_API_KEY}
     logging:
       level: info
       destination: 'cloudwatch'
     alerts:
       - metric: sync_failure_rate
         threshold: 0.05
         action: notify
       - metric: sync_lag
         threshold: 300  # seconds
         action: alert
   ```

7. **Database Schema**
   ```sql
   -- Sync state management
   CREATE TABLE sync_state (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     github_id VARCHAR(255),
     linear_id VARCHAR(255),
     github_updated_at TIMESTAMP,
     linear_updated_at TIMESTAMP,
     last_sync_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     sync_hash VARCHAR(64),
     sync_version INTEGER DEFAULT 1,
     metadata JSONB,
     UNIQUE(github_id, linear_id)
   );
   
   -- Sync history
   CREATE TABLE sync_history (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     sync_id UUID REFERENCES sync_state(id),
     direction VARCHAR(50),
     status VARCHAR(50),
     started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     completed_at TIMESTAMP,
     changes JSONB,
     errors JSONB
   );
   
   -- Conflict log
   CREATE TABLE sync_conflicts (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     sync_id UUID REFERENCES sync_state(id),
     detected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     conflict_type VARCHAR(100),
     github_data JSONB,
     linear_data JSONB,
     resolution VARCHAR(100),
     resolved_at TIMESTAMP,
     resolved_by VARCHAR(255)
   );
   
   -- Indexes for performance
   CREATE INDEX idx_sync_state_github_id ON sync_state(github_id);
   CREATE INDEX idx_sync_state_linear_id ON sync_state(linear_id);
   CREATE INDEX idx_sync_history_sync_id ON sync_history(sync_id);
   CREATE INDEX idx_sync_history_started_at ON sync_history(started_at);
   ```

8. **Monitoring Dashboard**
   ```javascript
   // monitoring/dashboard.js
   const metrics = {
     // Real-time metrics
     syncRate: new Rate('sync.operations'),
     syncDuration: new Histogram('sync.duration'),
     syncErrors: new Counter('sync.errors'),
     
     // Business metrics
     issuesSynced: new Counter('issues.synced'),
     conflictsResolved: new Counter('conflicts.resolved'),
     
     // System health
     apiLatency: new Histogram('api.latency'),
     queueDepth: new Gauge('queue.depth'),
     rateLimitRemaining: new Gauge('ratelimit.remaining')
   };
   
   // Dashboard configuration
   const dashboard = {
     title: 'GitHub-Linear Sync Monitor',
     widgets: [
       {
         type: 'timeseries',
         title: 'Sync Operations',
         metrics: ['sync.operations', 'sync.errors'],
         period: '1h'
       },
       {
         type: 'gauge',
         title: 'Queue Depth',
         metric: 'queue.depth',
         thresholds: [0, 50, 100, 200]
       },
       {
         type: 'heatmap',
         title: 'Sync Duration',
         metric: 'sync.duration',
         buckets: [100, 500, 1000, 5000, 10000]
       },
       {
         type: 'counter',
         title: 'Today\'s Syncs',
         metric: 'issues.synced',
         period: '1d'
       }
     ],
     alerts: [
       {
         name: 'High Error Rate',
         condition: 'rate(sync.errors) > 0.1',
         severity: 'critical'
       },
       {
         name: 'Sync Lag',
         condition: 'queue.depth > 100',
         severity: 'warning'
       }
     ]
   };
   ```

9. **Deployment Script**
   ```bash
   #!/bin/bash
   # deploy-sync-automation.sh
   
   set -e
   
   echo "🚀 Deploying GitHub-Linear Sync Automation"
   
   # Check prerequisites
   echo "📋 Checking prerequisites..."
   command -v gh >/dev/null 2>&1 || { echo "❌ GitHub CLI required"; exit 1; }
   command -v docker >/dev/null 2>&1 || { echo "❌ Docker required"; exit 1; }
   
   # Load configuration
   source .env
   
   # Build sync server
   echo "🔨 Building sync server..."
   docker build -t linear-sync-server .
   
   # Deploy database
   echo "🗄️ Setting up database..."
   docker-compose up -d postgres redis
   sleep 5
   docker-compose run --rm migrate
   
   # Configure webhooks
   echo "🔗 Configuring webhooks..."
   ./scripts/setup-webhooks.sh
   
   # Deploy sync server
   echo "🌐 Deploying sync server..."
   docker-compose up -d sync-server
   
   # Setup monitoring
   echo "📊 Configuring monitoring..."
   ./scripts/setup-monitoring.sh
   
   # Verify deployment
   echo "✅ Verifying deployment..."
   sleep 10
   curl -f http://localhost:3000/health || { echo "❌ Health check failed"; exit 1; }
   
   # Run initial sync
   echo "🔄 Running initial sync..."
   docker-compose run --rm sync-cli full-sync
   
   echo "✨ Deployment complete!"
   echo "📊 Dashboard: http://localhost:3000/dashboard"
   echo "📝 Logs: docker-compose logs -f sync-server"
   ```

10. **Maintenance Commands**
    ```bash
    # Sync management CLI
    linear-sync status          # Check sync status
    linear-sync pause          # Pause all syncing
    linear-sync resume         # Resume syncing
    linear-sync repair         # Repair sync state
    linear-sync reset          # Reset sync (caution!)
    
    # Troubleshooting
    linear-sync diagnose       # Run diagnostics
    linear-sync test-webhooks  # Test webhook connectivity
    linear-sync validate       # Validate configuration
    
    # Maintenance
    linear-sync cleanup        # Clean old sync records
    linear-sync export         # Export sync state
    linear-sync import         # Import sync state
    ```

## Examples

### Basic Setup
```bash
# Interactive setup
claude sync-automation-setup

# Setup with config file
claude sync-automation-setup --config="sync-config.yml"

# Minimal setup (webhooks only)
claude sync-automation-setup --mode="webhooks-only"
```

### Advanced Configuration
```bash
# Full automation with monitoring
claude sync-automation-setup \
  --mode="full" \
  --monitoring="datadog" \
  --alerts="slack,email"

# Custom deployment
claude sync-automation-setup \
  --deploy-target="kubernetes" \
  --namespace="sync-system"
```

### Maintenance
```bash
# Update webhook configuration
claude sync-automation-setup --update-webhooks

# Rotate secrets
claude sync-automation-setup --rotate-secrets

# Upgrade sync version
claude sync-automation-setup --upgrade
```

## Output Format

```
GitHub-Linear Sync Automation Setup
===================================

✅ Prerequisites Check
  ✓ GitHub CLI authenticated
  ✓ Linear MCP connected
  ✓ Database accessible
  ✓ Redis running

📋 Configuration Summary
  Mode: Bidirectional real-time sync
  Webhook URL: https://sync.company.com/webhooks
  Sync Interval: 5 minutes (incremental)
  Conflict Strategy: newer_wins

🔗 Webhook Configuration
  GitHub Webhooks:
    ✓ Issues webhook created (ID: 12345)
    ✓ Pull requests webhook created (ID: 12346)
    ✓ Webhook test successful
  
  Linear Webhooks:
    ✓ Issue webhook registered
    ✓ Comment webhook registered
    ✓ Webhook verified

🚀 Deployment Status
  ✓ Sync server deployed (3 replicas)
  ✓ Database migrations complete
  ✓ Redis queue initialized
  ✓ Monitoring configured

📊 Monitoring Setup
  Dashboard: https://monitoring.company.com/linear-sync
  Alerts configured:
    - Slack: #sync-alerts
    - Email: [email protected]
  
  Metrics collecting:
    - Sync rate
    - Error rate
    - API latency
    - Queue depth

🔒 Security Configuration
  ✓ Webhook secrets configured
  ✓ API keys encrypted
  ✓ TLS enabled
  ✓ Rate limiting active

📝 Next Steps
  1. Monitor initial sync: docker-compose logs -f
  2. Check dashboard for metrics
  3. Review sync-config.yml for customization
  4. Set up team notifications

Automation Status: ✅ ACTIVE
First sync scheduled: 2 minutes
```

## Best Practices

1. **Security**
   - Use webhook secrets
   - Encrypt API keys
   - Implement rate limiting
   - Regular secret rotation

2. **Reliability**
   - Implement retry logic
   - Use message queues
   - Monitor system health
   - Plan for failures

3. **Performance**
   - Optimize batch sizes
   - Implement caching
   - Use connection pooling
   - Monitor API limits

4. **Maintenance**
   - Regular health checks
   - Automated backups
   - Log retention policies
   - Update procedures

© BuildWithClaude Community · MIT · davepoon/buildwithclaude

Similar slash commands

All slash commands for Automation and no-code: n8n, Zapier, Make →

sync-automation-setup by other authors comes first.

From the same set235

The whole set →
mbse-requirements mbse-requirements is a Claude Code skill for reviewing and repairing system requirements with EARS patterns, measurable criteria, and stable IDs. It supports specification drafting and review. CX Codex +1 ★ 3,785repo stars constraint-modeler constraint-modeler turns a vague decision environment into a typed constraint map: hard limits, soft trade-offs, checked assumptions and scenario bounds. CX Codex +1 ★ 3,785repo stars remediation Generates a context-aware remediation plan for a vulnerability identifier with tailored update and verification commands. CX Codex +1 ★ 3,785repo stars timeline-compressor timeline-compressor turns a long real-world timeline into short simulation cycles: the command maps the phases, then runs compressed scenarios with confidence intervals attached. CX Codex +1 ★ 3,785repo stars market-response-modeler market-response-modeler is a Claude Code command for modeling customer and market reactions to business decisions. It kicks in for work involving audience segments and behavioral forecasts. CX Codex +1 ★ 3,785repo stars gsd-ui-auditor gsd-ui-auditor — a subagent for automated frontend audits after implementation. Reviews code and screenshots against six pillars, scores each, and writes a UI-REVIEW.md report. CX Codex ★ 3,785repo stars code-to-task code-to-task finds TODO comments, deprecated code, and technical debt markers across your repository to generate organized Linear tasks. CX Codex +1 ★ 3,785repo stars hard-predict-future The hard-predict-future skill examines future-facing questions with signals, historical analogues, and scenario analysis. Use it to assess outcomes involving markets, technology, or geopolitics. CX Codex +1 ★ 3,785repo stars

Project sponsors

Companies that keep this analytics open