linear-prod-checklist

name	linear-prod-checklist
description	Production readiness checklist for Linear integrations. Use when preparing to deploy, reviewing production requirements, or auditing existing Linear deployments. Trigger: "linear production checklist", "deploy linear", "linear production ready", "linear go live", "linear launch".
allowed-tools	Read, Write, Edit, Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","linear","deployment","audit"]
compatibility	Designed for Claude Code

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 }  ;

  {
  : { : ; :  };
  : { : ; : ; :  };
  : { : ; : ; :  };
  : { : ; :  };
}

 :  = {
  : {
    :  (),
    :  (),
  },
  : { : , : , :  },
  : { : , : , :  },
  : { : , :  },
};

 ():  {
    ({ : config.. });
}