/ci-cd

name: ci-cd
description: Use when building or fixing a delivery pipeline. Covers pipeline structure, caching, test parallelization, deployment strategies, secrets, and making the pipeline fast enough that people do not route around it. Trigger on "our ci takes 40 minutes", "flaky pipeline keeps failing", "set up github actions to deploy". Do not use for secret storage and rotation in general — see the secrets-management skill; for which tests to write, see the test-strategy skill.
metadata:
  category: devops
  version: 1.0.0
  tags: [ci-cd, github-actions, pipelines, deployment, automation]

CI/CD

Purpose

Build a pipeline that catches problems before production and is fast enough that engineers do not learn to ignore it. A twenty-minute CI run is a pipeline people bypass.

When to Use

• Setting up CI/CD for a new project.
• A pipeline that is slow, flaky, or routinely skipped.
• Introducing a safer deployment strategy.
• Managing secrets and deployment credentials.

Capabilities

• Pipeline structure: what runs on every commit, what runs on merge, what runs on release.
• Caching and parallelization to cut wall-clock time.
• Deployment strategies: blue/green, canary, rolling, feature flags.
• Secrets management and OIDC-based cloud authentication.
• Flaky-test detection and quarantine.

Inputs

• The repository, its test suite, and current pipeline timings.
• The deployment target and its rollback capability.
• Compliance requirements: approvals, audit trail, signed artifacts.

Outputs

• A pipeline with a fast feedback stage and a thorough merge stage.
• Deployments that are observable and reversible.
• No long-lived cloud credentials in CI.

Workflow

1. **Split fast from thorough** — Lint, type-check, and unit tests on every push, in under five minutes. Integration, E2E, and security scans on the merge queue or on main. 2. **Cache the right things** — Dependencies, build artifacts, and Docker layers. A cache keyed on the lockfile hash is correct; one keyed on the branch is a source of stale-build mysteries. 3. **Parallelize the test suite** — Shard by timing, not alphabetically. The slowest shard determines the wall clock. 4. **Deploy progressively** — Canary to a small percentage, watch the error rate and latency, then proceed. Automate the abort. 5. **Authenticate with OIDC** — Short-lived tokens federated from the CI provider to the cloud. A long-lived access key in CI secrets is a breach waiting to be exfiltrated by a malicious dependency. 6. **Track flakes** — A test that fails 2% of the time will train the team to re-run the pipeline reflexively, at which point CI has stopped working.

Best Practices

• A pipeline slower than about ten minutes changes behavior: people batch changes, stop pushing, and merge without waiting. Speed is a correctness property.
• Never allow a re-run to be the standard response to a red build. Quarantine the flaky test and fix it; re-running is how a real failure gets merged.
• Pin action and image versions by SHA, not by tag. A compromised or updated tag is a supply-chain compromise with commit access.
• Deployment must be a single button (or a single merge) with a single rollback. If deploying requires a runbook of six manual steps, one of them will be skipped at 2am.
• Build the artifact once and promote it through environments. Rebuilding per environment means the thing you tested is not the thing you shipped.
• The pipeline's own configuration is code: review it, and restrict who can change the deployment steps.

Examples

**Pipeline with fast feedback, sharded tests, and OIDC deployment:**

name: ci
on: [push, pull_request]

jobs:
  fast:                                   # < 5 min: runs on every push
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4, pinned by SHA
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npm run lint && npm run typecheck

  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]               # sharded by recorded timings
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npm test -- --shard=${{ matrix.shard }}/4

  deploy:
    needs: [fast, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      id-token: write                     # OIDC: no stored AWS keys anywhere
      contents: read
    environment: production               # requires approval, records an audit trail
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/deploy
          aws-region: eu-west-1
      - run: ./scripts/deploy.sh --canary 10 --abort-on-error-rate 1.0

Notes

• OIDC federation removes long-lived cloud credentials from CI entirely. This is the single highest-value security change available to most pipelines, and it takes an afternoon.
• `fail-fast: false` on a test matrix means you see all the failures in one run rather than the first one — significantly cheaper in wall-clock terms when several shards fail.
• A merge queue (GitHub merge queue, Zuul, Bors) tests the *merged* result rather than the branch, which prevents the semantic conflict where two independently green PRs break main together.