Deployment Patterns

Deployment Patterns

Production deployment workflows and CI/CD best practices.

When to Activate

• Setting up CI/CD pipelines
• Planning deployment strategy (blue-green, canary, rolling)
• Implementing health checks and readiness probes
• Preparing for a production release
• Configuring environment-specific settings

Deployment Strategies

Rolling Deployment (Default)

Replace instances gradually — old and new versions run simultaneously during rollout.

Instance 1: v1 → v2  (update first)
Instance 2: v1        (still running v1)
Instance 3: v1        (still running v1)

Instance 1: v2
Instance 2: v1 → v2  (update second)
Instance 3: v1

Instance 1: v2
Instance 2: v2
Instance 3: v1 → v2  (update last)

Pros: Zero downtime, gradual rollout Cons: Two versions run simultaneously — requires backward-compatible changes Use when: Standard deployments, backward-compatible changes

Blue-Green Deployment

Run two identical environments. Switch traffic atomically.

Blue  (v1) ← traffic
Green (v2)   idle, running new version

# After verification:
Blue  (v1)   idle (becomes standby)
Green (v2) ← traffic

Pros: Instant rollback (switch back to blue), clean cutover Cons: Requires 2x infrastructure during deployment Use when: Critical services, zero-tolerance for issues

Canary Deployment

Route a small percentage of traffic to the new version first.

v1: 95% of traffic
v2:  5% of traffic  (canary)

# If metrics look good:
v1: 50% of traffic
v2: 50% of traffic

# Final:
v2: 100% of traffic

Pros: Catches issues with real traffic before full rollout Cons: Requires traffic splitting infrastructure, monitoring Use when: High-traffic services, risky changes, feature flags

Docker

For Dockerfiles, Compose, image hardening, volumes, and container debugging, see the docker-patterns skill (plugins/web/skills/docker-patterns/SKILL.md) — this skill covers what surrounds the image: pipelines, probes, rollout, and rollback.

CI/CD Pipeline

GitHub Actions (Standard Pipeline)

Action majors below were current as of 2026-08 (verified against each repo's releases). They rot: before copying, check with gh api repos/<owner>/<repo>/releases/latest --jq .tag_name. Recent majors mainly moved to the Node 24 runtime — GitHub-hosted runners are always compatible, but self-hosted runners must be ≥ 2.327.1.

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24   # active LTS as of 2026-08; 22 is in maintenance
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: coverage
          path: coverage/

  build:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v7
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    environment: production
    steps:
      - name: Deploy to production
        run: |
          # Platform-specific deployment command
          # Railway: railway up
          # Vercel: vercel --prod
          # K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
          echo "Deploying ${{ github.sha }}"

Pipeline Stages

PR opened:
  lint → typecheck → unit tests → integration tests → preview deploy

Merged to main:
  lint → typecheck → unit tests → integration tests → build image → deploy staging → smoke tests → deploy production

Health Checks

Health Check Endpoint

// Simple health check
app.get("/health", (req, res) => {
  res.status(200).json({ status: "ok" });
});

// Detailed health check (for internal monitoring)
app.get("/health/detailed", async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    redis: await checkRedis(),
    externalApi: await checkExternalApi(),
  };

  const allHealthy = Object.values(checks).every(c => c.status === "ok");

  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? "ok" : "degraded",
    timestamp: new Date().toISOString(),
    version: process.env.APP_VERSION || "unknown",
    uptime: process.uptime(),
    checks,
  });
});

async function checkDatabase(): Promise<HealthCheck> {
  try {
    await db.query("SELECT 1");
    return { status: "ok", latency_ms: 2 };
  } catch (err) {
    return { status: "error", message: "Database unreachable" };
  }
}

Kubernetes Probes

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 30
  failureThreshold: 3

# Liveness stays shallow on purpose: if it checked the database, a DB outage
# would make Kubernetes restart every healthy pod. Readiness is where a
# dependency check belongs — failing readiness only sheds traffic, so point it
# at a handler that verifies critical dependencies (like /health/detailed
# above) when your service cannot serve without them.
readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 2

startupProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30    # 30 * 5s = 150s max startup time

Environment Configuration

Twelve-Factor App Pattern

# All config via environment variables — never in code
DATABASE_URL=postgres://user:pass@host:5432/db   # placeholder — real values come from the platform's secret store, and any plaintext .env stays in .gitignore
REDIS_URL=redis://host:6379/0
API_KEY=${API_KEY}           # injected by secrets manager
LOG_LEVEL=info
PORT=3000

# Environment-specific behavior
NODE_ENV=production          # or staging, development
APP_ENV=production           # explicit app environment

Configuration Validation

import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "staging", "production"]),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

// Validate at startup — fail fast if config is wrong
export const env = envSchema.parse(process.env);

Rollback Strategy

Instant Rollback

# Docker/Kubernetes: point to previous image
kubectl rollout undo deployment/app

# Vercel: promote previous deployment
vercel rollback

# Railway: pick a previous deployment and redeploy it
railway deployment list
railway redeploy   # redeploys the latest; use the dashboard to restore older ones

Application rollback is instant. Schema rollback is not — see below.

Database: There Is No Instant Rollback

prisma migrate resolve --rolled-back <name> does not revert an applied migration. It sets rolled_back_at on a failed migration's row in _prisma_migrations so migrate deploy can retry it. On a migration that succeeded, Prisma refuses outright:

Error: P3012 Migration `<name>` cannot be rolled back because it is not in a failed state.

migrate deploy has no automatic down migrations, and there is no single command that reverts an applied one. Reverting means writing and testing the inverse migration yourself, then deploying it like any other — which is why the expand/contract discipline below matters more than any rollback command.

Rollback Checklist

• Previous image/artifact is available and tagged
• Previous app version verified against the current schema (expand/contract)
• Any destructive schema change (drop/rename/narrow) is deferred to a later release
• Feature flags can disable new features without deploy
• Monitoring alerts configured for error rate spikes
• Rollback tested in staging before production release

Production Readiness Checklist

Before any production deployment:

Application

• All tests pass (unit, integration, E2E)
• No hardcoded secrets in code or config files
• Error handling covers all edge cases
• Logging is structured (JSON) and does not contain PII
• Health check endpoint returns meaningful status

Infrastructure

• Docker image builds reproducibly (pinned versions)
• Environment variables documented and validated at startup
• Resource limits set (CPU, memory)
• Horizontal scaling configured (min/max instances)
• SSL/TLS enabled on all endpoints

Monitoring

• Application metrics exported (request rate, latency, errors)
• Alerts configured for error rate > threshold
• Log aggregation set up (structured logs, searchable)
• Uptime monitoring on health endpoint

Security

• Dependencies scanned for CVEs
• CORS configured for allowed origins only
• Rate limiting enabled on public endpoints
• Authentication and authorization verified
• Security headers set (CSP, HSTS, X-Frame-Options)

Operations

• Rollback plan documented and tested
• Database migration tested against production-sized data
• Runbook for common failure scenarios
• On-call rotation and escalation path defined