Linear CI/CD Automation - Production Workflows That Actually Work

Set up a GitHub Action that hits Linear's API after successful deployments. The trick is using Linear's GraphQL mutations to update issue state based on your deployment environment. Here's what actually works:

## .github/workflows/deploy-prod.yml
- name: Update Linear issues on prod deploy
  run: |
    curl -X POST https://api.linear.app/graphql \
      -H "Authorization: ${{ secrets.LINEAR_API_KEY }}" \
      -d '{"query": "mutation { issueUpdate(id: \"${{ github.event.head_commit.message | grep -o \"LIN-[0-9]*\" }}\", input: { stateId: \"completed-state-id\" }) { success } }"}'

The gotcha? You need to extract the Linear issue ID from commit messages, and Linear's state IDs are UUIDs that change per team. Budget 2 hours to get this working the first time.

Linear's webhook system has a dirty secret: it can't handle burst traffic. During a deployment with 50+ commits, webhooks start timing out after 5 seconds. I learned this the hard way when our monorepo deployment failed silently - Linear never received the webhook. The solution is implementing exponential backoff and queuing:

// Webhook handler that won't crash during deployment spikes
async function handleLinearWebhook(payload) {
  const maxRetries = 3;
  const delay = (attempt) => Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      await processWebhook(payload);
      break;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, delay(attempt)));
    }
  }
}

Linear allows 1,500 requests per hour (about 25 per minute), but here's the catch: that's per user, not per workflow. If you have 20 GitHub Actions hitting Linear simultaneously during a big merge, you'll start getting 429 errors since all requests share the same user quota.

The fix is batching operations and using a request queue. We learned this when our deployment pipeline started failing randomly - turned out we were making 47 API calls per deploy (checking PR status, updating issues, posting comments). Now we batch updates into single GraphQL mutations and queue requests through a central service.

The naive approach creates an issue for every failed test, which floods your backlog with garbage.

Instead, create issues only for regressions and group failures by error pattern:

## Only create issues for failures on main branch (regressions)
- name:

 Create Linear issue for regression
  if: failure() && github.ref == 'refs/heads/main'
  run: |
    # Check if issue already exists for this error pattern
    error_hash=$(echo "${{ steps.test.outputs.error }}" | sha256sum | cut -d' ' -f1)
    existing=$(curl -s -X POST https://api.linear.app/graphql \
      -H "Authorization: ${{ secrets.

LINEAR_API_KEY }}" \
      -d "{\"query\": \"query { issues(filter: { title: { containsIgnoreCase: \\\"$error_hash\\\" } }) { nodes { id } } }\"}")
    
    if [[ $(echo $existing | jq '.data.issues.nodes | length') -eq 0 ]]; then
      # Create new issue only if one doesn't exist
      curl -X POST https://api.linear.app/graphql \
        -H "Authorization: ${{ secrets.

LINEAR_API_KEY }}" \
        -d "{\"query\": \"mutation { issueCreate(input: { teamId: \\\"$TEAM_ID\\\", title: \\\"CI Regression: $error_hash\\\", description: \\\"${{ steps.test.outputs.error }}\\\" }) { issue { id url } } }\"}"
    fi

This prevents duplicate issues and focuses on actual problems instead of flaky tests.

Sort of. The built-in GitHub integration works great for simple workflows (PR created → issue moves to "In Progress"), but falls apart with complex pipelines that have staging, QA, and production environments.

Linear's sync assumes a linear progression (pun intended), but real deployments look like this:

1. PR merged → Deploy to staging → QA testing → Deploy to prod → Issue closed

The built-in integration only handles steps 1 and 5. For everything else, you need custom webhooks and API calls to track deployment status across environments.

Rollbacks are where most Linear automations fall apart.

You deploy, Linear marks issues as "Done", then you rollback due to a critical bug. Now Linear thinks the features are shipped when they're actually broken in production.The solution is treating rollbacks as first-class events in your automation:```yaml# Rollback workflow that updates Linear

• name:

Handle rollback in Linear run: | # Find all issues that were marked done in the last deployment 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```Track rollbacks with labels so you can measure rollback frequency and impact on your backlog.

Linear's API availability is solid (~99.9%), but when it fails, your entire deployment automation fails too.

We learned this the hard way during a Black Friday incident

• Linear's API was returning 500s for 20 minutes while we were trying to deploy a critical cart fix. Our entire GitHub Actions pipeline was blocked waiting for Linear webhook confirmations.The fix is making Linear updates optional for critical deployments:```yaml
• name:

Deploy (never fails due to Linear) run: | # Core deployment logic here

• name:

Update Linear (best effort) continue-on-error: true # Don't fail deployment if Linear is down run: | # Linear API calls here

• name:

Queue Linear update for retry if: failure() run: | # Add to retry queue for when Linear comes back online echo "${{ github.sha }},$(date),deployment-success" >> /tmp/linear-retry-queue.csv```Always prioritize deployment success over Linear updates. You can backfill issue statuses later.

Managing Linear API keys across 20+ microservice repos is a nightmare.

Each repo needs access to update issues, but you don't want to copy the same API key everywhere (security risk and rotation nightmare).The solution is centralized Linear automation through a dedicated service:```javascript// central-linear-service.js

• Single API key, multiple reposconst express = require('express');const app = express(); // Webhook endpoint for all reposapp.post('/update-linear', express.json(), async (req, res) => { const { repo, action, issues, environment } = req.body; // Validate request is from authorized repo if (!is

AuthorizedRepo(repo, req.headers.authorization)) { return res.status(401).send('Unauthorized'); } for (const issueId of issues) { await updateLinearIssue(issueId, action, environment, repo); } res.json({ success: true });}); // Each repo calls this instead of Linear API directlyasync function update

LinearIssue(issueId, action, environment, repo) { const stateId = getStateIdForAction(action, environment); const label = ${repo}-${environment}; await callLinearAPI(` mutation { issueUpdate(id: "${issue

Id}", input: { stateId: "${state

Id}", labels: ["${label}"] }) { success } } `);}```This centralizes API key management and makes it easier to implement consistent automation patterns across all repos.

Linear's binary thinking (issue is done vs not done) doesn't match modern deployment practices.

When you deploy behind a feature flag to 5% of users, is the issue "done"? What about when the feature is live but disabled?We handle this by creating intermediate states:

• "Deployed (Flagged)"
• Code is in prod but behind a flag
• "Enabled (5%)"
• Feature is live for a subset of users
• "Enabled (100%)"
• Full rollout complete, issue actually done```yaml# Feature flag deployment automation
• 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 } }\"}"```This gives product managers visibility into gradual rollout progress without confusing deployment state.

Automated issue updates generate a lot of noise.

Every status change, label addition, and comment creates notifications. During a big deployment with 50+ issues, your team gets flooded with Linear notifications.Linear's API doesn't have a "silent update" option, but you can minimize noise by:

1. Batching updates:

Update multiple issues in a single API call when possible 2. Using dedicated automation accounts: Create a separate Linear account for automation so updates are clearly automated 3. Selective notifications:

Only notify on important state changes (deployed to prod, not staging)```javascript// Batch issue updates to reduce notification spamasync function batch

UpdateIssues(issueIds, newStateId) { const mutations = issueIds.map((id, index) => update${index}: issueUpdate(id: "${id}", input: { stateId: "${newStateId}" }) { success } ).join(' '); const query = mutation { ${mutations} }; return await callLinearAPI(query);}```

Linear uses operational transformation (similar to Google Docs) to handle concurrent updates, but it's not perfect.

If two automation workflows update the same issue simultaneously, you can get race conditions where the last update wins and previous changes are lost.We've seen this with incident management workflows where multiple systems try to update the same issue:

• Git

Hub Actions marks issue as "Deployed"

• Monitoring system marks it as "Failed"
• PagerDuty marks it as "Incident"I spent 2 hours debugging why our deployment success notifications were getting lost, only to find they were being overwritten by subsequent monitoring updates 30 seconds later.

The last update wins, losing deployment and failure context. The solution is using Linear's updatedAt timestamp for optimistic locking:```javascript// Safe concurrent updates with optimistic lockingasync function safe

UpdateIssue(issueId, updates) { // Get current issue state const current = await getIssue(issueId); const currentUpdatedAt = current.updatedAt; // Perform update with timestamp check try { await updateIssue(issueId, { ...updates, expectedUpdatedAt: current

UpdatedAt }); } catch (error) { if (error.message.includes('stale')) { // Issue was updated by someone else, retry with fresh data await safeUpdateIssue(issueId, updates); } throw error; }}```This prevents lost updates but adds complexity to your automation logic.