Linear CI/CD Automation: Production Implementation Guide

Configuration Requirements

API Access and Rate Limits

• Rate Limit: 1,500 requests/hour (25/minute) per user
• Critical Warning: Limit is per user, not per workflow - multiple GitHub Actions using same API key compete for quota
• Failure Point: 20+ simultaneous workflows will trigger 429 errors
• Solution: Use separate API keys for different workflow types or implement request queueing

Required State IDs (Team-Specific UUIDs)

# Query team state IDs (required for automation)
curl -X POST "https://api.linear.app/graphql" \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -d '{"query": "query { team(id: \"team-id\") { states { nodes { id name } } } }"}'

• Store as GitHub repository secrets
• Different for every Linear team
• Cannot be hardcoded in workflows

Webhook Reliability Issues

• Breaking Point: 50+ concurrent commits cause webhook timeouts (5-second limit)
• Undocumented Limitation: Linear's webhook system cannot handle burst traffic
• Required Solution: Implement exponential backoff and request queueing

Production-Ready Implementation

GitHub Actions Workflow (Environment-Aware)

name: Production Deployment with Linear Integration

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Extract Linear issue IDs from commits
        id: linear-issues
        run: |
          issues=$(git log --oneline ${{ github.event.before }}..${{ github.event.after }} | grep -o 'LIN-[0-9]\+' | sort | uniq | tr '\n' ',' | sed 's/,$//')
          echo "issues=$issues" >> $GITHUB_OUTPUT

      - name: Update issues to "Deploying"
        if: steps.linear-issues.outputs.issues != ''
        run: |
          IFS=',' read -ra ISSUE_ARRAY <<< "${{ steps.linear-issues.outputs.issues }}"
          for issue in "${ISSUE_ARRAY[@]}"; do
            curl -X POST https://api.linear.app/graphql \
              -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
              -H "Content-Type: application/json" \
              -d "{\"query\": \"mutation { issueUpdate(id: \\\"$issue\\\", input: { stateId: \\\"${{ vars.LINEAR_DEPLOYING_STATE_ID }}\\\" }) { success } }\"}"
          done

      - name: Deploy to production
        id: deploy
        run: |
          # Deployment logic here
          echo "Deploying to production..."
          
      - name: Mark issues as completed on successful deploy
        if: success() && steps.linear-issues.outputs.issues != ''
        run: |
          IFS=',' read -ra ISSUE_ARRAY <<< "${{ steps.linear-issues.outputs.issues }}"
          for issue in "${ISSUE_ARRAY[@]}"; do
            curl -X POST https://api.linear.app/graphql \
              -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
              -H "Content-Type: application/json" \
              -d "{\"query\": \"mutation { issueUpdate(id: \\\"$issue\\\", input: { stateId: \\\"${{ vars.LINEAR_DONE_STATE_ID }}\\\" }) { success } }\"}"
          done

      - name: Create incident issue on deployment failure
        if: failure()
        run: |
          curl -X POST https://api.linear.app/graphql \
            -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"query\": \"mutation { issueCreate(input: { teamId: \\\"${{ vars.LINEAR_INCIDENTS_TEAM_ID }}\\\", title: \\\"Production deployment failed - $(date)\\\", description: \\\"Deployment workflow failed. Check: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\\\", priority: 1 }) { issue { id url } } }\"}"

Reliable Webhook Processor (Required for Scale)

// webhook-processor.js - Handles webhook failures during traffic spikes
const express = require('express');
const Queue = require('bull');

const webhookQueue = new Queue('Linear webhook processing');
const app = express();

// Queue webhooks instead of immediate processing (prevents timeout failures)
app.post('/webhook/linear', express.json(), (req, res) => {
  webhookQueue.add('process', req.body, {
    attempts: 5,
    backoff: {
      type: 'exponential',
      delay: 2000,
    },
  });
  
  res.status(200).send('Queued');
});

// Process with rate limit handling
webhookQueue.process('process', async (job) => {
  const { data: webhook } = job;
  
  try {
    await processLinearWebhook(webhook);
  } catch (error) {
    if (error.response?.status === 429) {
      throw new Error('Rate limited - will retry');
    }
    throw error;
  }
});

Critical Failure Scenarios

Built-in GitHub Integration Limitations

• Fails with: Cherry-picks, merge conflicts, multi-environment deployments
• False Positives: Marks issues "Done" when staging deploy fails but PR merged
• No Environment Awareness: Cannot distinguish staging vs production deployments
• Breaking Point: Any workflow more complex than single-environment deployment

Rollback Handling (Commonly Overlooked)

# Rollback workflow - prevents "ghost completed" issues
- name: Handle rollback in Linear
  run: |
    rollback_issues=$(git log --oneline ${{ github.event.inputs.rollback_to }}..${{ github.sha }} | grep -o 'LIN-[0-9]\+' | sort | uniq)
    for issue in $rollback_issues; do
      curl -X POST https://api.linear.app/graphql \
        -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
        -d "{\"query\": \"mutation { issueUpdate(id: \\\"$issue\\\", input: { stateId: \\\"${{ vars.LINEAR_REOPENED_STATE_ID }}\\\", labels: [\\\"rollback-$(date +%Y%m%d)\\\"] }) { success } }\"}"
    done

Concurrent Update Race Conditions

• Problem: Multiple systems updating same issue simultaneously causes data loss
• Frequency: Common with incident management workflows
• Impact: Last update wins, losing deployment/failure context
• Solution: Implement optimistic locking with updatedAt timestamps

Resource Requirements

Implementation Time Investment

• Initial Setup: 3 days (includes debugging undocumented edge cases)
• First Working Version: 2 hours (basic webhook integration)
• Production-Ready: 2-3 weeks (including error handling and monitoring)

Operational Overhead

• Performance Impact: +30 seconds per deployment (acceptable for production)
• API Monitoring Required: Linear provides no usage dashboards
• Maintenance: Weekly monitoring of rate limits and webhook failures

Team Savings

• Estimated Time Saved: 15 hours/week for engineering team
• ROI Break-even: 2 weeks after implementation
• Manual Status Updates Eliminated: 100% for successful deployments

Multi-Environment State Management

Required Custom States

• "Deploying": Code deployment in progress
• "Deployed (Flagged)": Code in production behind feature flag
• "Enabled (X%)": Feature live for percentage of users
• "Deployed Staging": Successfully deployed to staging environment
• "Deployed Production": Live in production, issue complete

Feature Flag Integration

- name: Update for flagged deployment
  run: |
    curl -X POST https://api.linear.app/graphql \
      -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
      -d "{\"query\": \"mutation { issueUpdate(id: \\\"$issue_id\\\", input: { stateId: \\\"${{ vars.LINEAR_DEPLOYED_FLAGGED_STATE_ID }}\\\", labels: [\\\"feature-flag\\\"] }) { success } }\"}"

- name: Update for percentage rollout
  run: |
    rollout_percent="${{ github.event.inputs.rollout_percentage }}"
    curl -X POST https://api.linear.app/graphql \
      -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
      -d "{\"query\": \"mutation { issueUpdate(id: \\\"$issue_id\\\", input: { labels: [\\\"enabled-${rollout_percent}%\\\"] }) { success } }\"}"

Security Requirements

Webhook Validation (Critical)

• Vulnerability: Linear doesn't include webhook signatures by default
• Risk: Public endpoints can be spammed with fake deployment updates
• Real Impact: Competitor spam attacks causing false deployment status
• Required Solution: Implement HMAC signature validation

const crypto = require('crypto');

function validateLinearWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

API Performance Monitoring

Required Metrics Tracking

// Essential monitoring for Linear API health
const linearApiCall = async (query) => {
  const start = Date.now();
  try {
    const response = await fetch('https://api.linear.app/graphql', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}` },
      body: JSON.stringify({ query })
    });
    
    // Critical metrics to track
    console.log('Rate limit remaining:', response.headers.get('X-RateLimit-Remaining'));
    console.log('API response time:', Date.now() - start, 'ms');
    
    return response.json();
  } catch (error) {
    console.error('Linear API failed:', error);
    throw error;
  }
};

Alternative Comparison Matrix

Tool	API Quality	Rate Limits	Webhook Reliability	Multi-Environment	Automation Complexity
Linear	GraphQL (excellent)	1000 req/min	Good (fails during spikes)	Custom states required	Medium
Jira	REST (poor)	300 req/hr	Terrible	Workflow hell	High
GitHub Issues	REST (decent)	5000 req/hr	Excellent	Labels only	Low
Azure DevOps	REST (complex)	200 req/min	Decent	Built-in but heavy	High

Critical Decision Factors

When Linear Automation is Worth It

• Team size: 5+ engineers
• Deployment frequency: Daily or higher
• Multi-environment pipelines
• Feature flag usage
• Incident management integration needs

When to Use Alternatives

• GitHub Issues: Simple workflows, single environment
• Jira: Enterprise compliance requirements (despite poor API)
• Azure DevOps: Microsoft ecosystem integration required

Implementation Prerequisites

Required Technical Knowledge

• GraphQL query construction
• GitHub Actions workflow syntax
• Webhook security best practices
• Node.js/Express.js for webhook processing
• Basic understanding of CI/CD pipeline architecture

Infrastructure Requirements

• Dedicated webhook processing service
• Redis/Bull queue for reliability
• API key rotation capabilities
• Monitoring and alerting for API failures

Operational Warnings

Will Break During

• High-traffic deployments (50+ commits)
• Linear API outages (rare but critical)
• Rate limit exhaustion from multiple workflows
• Concurrent issue updates from multiple systems

Requires Ongoing Maintenance

• Weekly rate limit monitoring
• Webhook endpoint health checks
• API key rotation procedures
• State ID validation after Linear team changes