linear-prod-checklist

Linear Production Checklist

Overview

Comprehensive checklist and implementation patterns for deploying Linear integrations to production. Covers authentication, error handling, rate limiting, monitoring, data handling, and deployment verification.

Prerequisites

• Working development integration passing all tests
• Production Linear workspace (or production API key)
• Deployment infrastructure (Vercel, Cloud Run, etc.)
• Secret management solution (not .env files in production)

Pre-Production Checklist

1. Authentication & Security

[ ] Production API key generated (separate from dev)
[ ] API key stored in secret manager (Vault, AWS SM, GCP SM)
[ ] OAuth redirect URIs updated for production domain
[ ] Webhook secrets are unique per environment
[ ] All dev secrets rotated before launch
[ ] HTTPS enforced on all endpoints
[ ] Webhook HMAC-SHA256 verification implemented
[ ] Webhook timestamp validation (< 60s age)
[ ] Token refresh flow implemented (mandatory since Oct 2025)

2. Error Handling & Resilience

[ ] All Linear API calls wrapped in try/catch
[ ] Rate limit retry with exponential backoff (max 5 retries)
[ ] 30s timeout on all API calls
[ ] Graceful degradation when Linear API is down
[ ] Error logging includes context (no secrets in logs)
[ ] InvalidInputLinearError caught separately from network errors
[ ] Alerts configured for auth failures and error rate spikes

3. Performance & Rate Limits

[ ] Pagination with first:50 for all list queries
[ ] Caching for static data (teams, states, labels) — 10-30 min TTL
[ ] Request batching for bulk operations (20 mutations per batch)
[ ] Query complexity stays under 5,000 pts per request
[ ] No polling — webhooks for real-time updates
[ ] N+1 query patterns eliminated (use rawRequest for joins)
[ ] Response times monitored with p95 alerting

4. Monitoring & Observability

[ ] Health check endpoint hitting Linear API
[ ] API latency metrics collected per operation
[ ] Error rate monitoring with alerting (>1% = alert)
[ ] Rate limit remaining tracked (alert if < 100 requests)
[ ] Structured JSON logging for API calls and webhooks
[ ] Webhook delivery tracking via Linear-Delivery header

5. Data Handling

[ ] No PII logged or stored unnecessarily
[ ] Webhook event idempotency (deduplicate by Linear-Delivery)
[ ] Data retention policy defined for synced data
[ ] Stale data detection with periodic consistency checks

Production Configuration

import { LinearClient } from "@linear/sdk";

interface ProdConfig {
  linear: { apiKey: string; webhookSecret: string };
  rateLimit: { maxRetries: number; baseDelayMs: number; maxDelayMs: number };
  cache: { teamsTtl: number; statesTtl: number; labelsTtl: number };
  timeouts: { requestMs: number; webhookProcessMs: number };
}

const config: ProdConfig = {
  linear: {
    apiKey: await getSecret("linear-api-key-prod"),
    webhookSecret: await getSecret("linear-webhook-secret-prod"),
  },
  rateLimit: { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 30000 },
  cache: { teamsTtl: 600, statesTtl: 1800, labelsTtl: 600 },
  timeouts: { requestMs: 30000, webhookProcessMs: 5000 },
};

function createProductionClient(): LinearClient {
  return new LinearClient({ apiKey: config.linear.apiKey });
}

Health Check Implementation

interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  latencyMs: number;
  details: {
    authentication: boolean;
    apiReachable: boolean;
    rateLimitOk: boolean;
  };
  timestamp: string;
}

async function checkHealth(client: LinearClient): Promise<HealthStatus> {
  const start = Date.now();
  const details = { authentication: false, apiReachable: false, rateLimitOk: true };

  try {
    const viewer = await client.viewer;
    details.authentication = true;
    details.apiReachable = true;

    const latencyMs = Date.now() - start;
    return {
      status: latencyMs > 3000 ? "degraded" : "healthy",
      latencyMs,
      details,
      timestamp: new Date().toISOString(),
    };
  } catch (error: any) {
    details.apiReachable = !error.message?.includes("ENOTFOUND");
    return {
      status: "unhealthy",
      latencyMs: Date.now() - start,
      details,
      timestamp: new Date().toISOString(),
    };
  }
}

// Express endpoint
app.get("/health/linear", async (req, res) => {
  const health = await checkHealth(client);
  res.status(health.status === "unhealthy" ? 503 : 200).json(health);
});

Deployment Verification Script

// scripts/verify-deployment.ts
import { LinearClient } from "@linear/sdk";

async function verify(): Promise<void> {
  console.log("Verifying Linear integration...\n");

  const checks = [
    {
      name: "Environment variables",
      check: async () => !!(process.env.LINEAR_API_KEY && process.env.LINEAR_WEBHOOK_SECRET),
    },
    {
      name: "API authentication",
      check: async () => { await new LinearClient({ apiKey: process.env.LINEAR_API_KEY! }).viewer; return true; },
    },
    {
      name: "Team access",
      check: async () => {
        const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });
        const teams = await client.teams();
        return teams.nodes.length > 0;
      },
    },
    {
      name: "Write capability",
      check: async () => {
        const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });
        const teams = await client.teams();
        const r = await client.createIssue({
          teamId: teams.nodes[0].id,
          title: "[DEPLOY-CHECK] Safe to delete",
        });
        if (r.success) {
          const issue = await r.issue;
          await issue?.delete();
        }
        return r.success;
      },
    },
  ];

  let passed = 0;
  let failed = 0;

  for (const { name, check } of checks) {
    try {
      const ok = await check();
      console.log(ok ? `  PASS: ${name}` : `  FAIL: ${name}`);
      ok ? passed++ : failed++;
    } catch (error: any) {
      console.log(`  FAIL: ${name} — ${error.message}`);
      failed++;
    }
  }

  console.log(`\nResults: ${passed} passed, ${failed} failed`);
  if (failed > 0) process.exit(1);
}

verify();

Post-Deployment Monitoring

// Key metrics to track after deploy
const ALERT_THRESHOLDS = {
  errorRate: 0.01,        // Alert if >1% of requests fail
  p99LatencyMs: 3000,     // Alert if p99 > 3 seconds
  rateLimitRemaining: 100, // Alert if remaining requests < 100
};

// First 30 minutes after deploy: watch for
// - Auth failures (key mismatch between environments)
// - Rate limit spikes (init burst fetching too much data)
// - Webhook signature failures (secret not updated in new env)

Error Handling

Issue	Cause	Solution
Health check unhealthy	API key invalid/expired	Regenerate key, update secret manager
Webhook sig fails in prod	Secret mismatch	Verify LINEAR_WEBHOOK_SECRET matches Linear webhook config
Rate limit burst on deploy	Startup fetches too much	Add request queue, cache static data
Deploy verification fails	Missing env vars	Run verification locally first

Resources

• Linear API Status
• Linear Security
• API Changelog