Pipeline performance: caching, parallelism, fail-fast

Caching: the right key is a lockfile hash

When you’re looking at a slow pipeline and wondering where to start, the answer is almost always the same: cache what’s deterministic, and put the fast checks first. Here is how each piece works.

Every CI job starts on a clean runner, so without a cache it redoes every expensive deterministic step — chiefly the dependency install — from scratch on each run. A cache fixes that, but only if its key is right. The key is a string; a cache hits when that exact string already exists, otherwise it misses and a fresh cache is saved at the end of a successful job. So the key must change exactly when the cached contents should change, and never otherwise.

For dependencies the input that determines node_modules is the lockfile, so you hash it with hashFiles. Add restore-keys as an ordered list of prefixes: on a miss, GitHub walks them in order and restores the most recent cache whose key starts with the prefix — a partial hit, so npm ci reinstalls only the delta instead of all 1,200 packages over the network.

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node22-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node22-
      ${{ runner.os }}-

There are three cache layers worth distinguishing, each keyed the same way: the dependency cache (~/.npm, ~/.cache/pip, Go module cache — often automatic via setup-node’s cache: npm), the build cache (incremental compiler output, Turborepo/Nx remote cache), and the Docker layer cache (type=gha with buildx). The anti-pattern that kills all three is the same: a volatile key. Bake a timestamp or ${{ github.run_id }} into the key and it is unique every run — so it never hits, the cache silently saves and is never read, and you pay full install time forever while believing you have a cache.

Fail-fast: cheapest, most-likely-to-fail first

needs turns a flat list of jobs into a DAG: a job with needs: [lint] will not start until lint succeeds. That single keyword lets you gate the slow, expensive work behind the cheap work — so a two-second lint failure short-circuits the run before a twenty-minute e2e suite ever boots a browser. The ordering rule is cheapest and most-likely-to-fail first: lint and typecheck run in seconds and catch the most common mistakes, so they go at the front of the DAG and everything slow hangs off them with needs.

jobs:
  lint:                       # ~10 s — the cheap gate
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: npm run lint && npm run typecheck }]

  unit:
    needs: lint               # never starts if lint fails
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: npm test }]

  build:
    needs: lint               # parallel with unit — both only need lint
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: npm run build }]

  e2e:
    needs: [unit, build]      # the slow suite is gated behind everything cheap
    strategy:
      fail-fast: true         # one shard fails → cancel the rest
      matrix:
        browser: [chromium, firefox, webkit]
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: npx playwright test --project=${{ matrix.browser }} }]

Parallelism and a matrix: split work, but fan-out isn’t free

When jobs are independent — unit and build above both only need lint — they run in parallel automatically, cutting wall-clock time. A matrix is the compact way to fan one job over a list (browsers, Node versions, OSes), spawning one job per cell. The catch is cost. GitHub bills each job’s minutes independently and rounds each job up to the whole minute, so a 3-browser × 2-OS matrix is six separate jobs, each paying its own checkout, install, and cache-restore overhead. Parallelism trades billable minutes for latency: five 1-minute shards finish in one minute of wall-clock but bill five minutes. Fan out where the latency win is real; cap runaway fan-out with max-parallel.

Cost: minutes, runner size, and idle

Before reaching for a bigger runner or a wider matrix, ask yourself: will this job actually run faster, or will the extra cores just sit idle and bill me more?

Runner minutes are the bill. Linux is the cheap baseline; Windows costs roughly 2× per minute and macOS roughly 10×, so a careless macOS matrix is the fastest way to a surprise invoice. Two more levers cut both ways. A bigger runner (more vCPUs) finishes a CPU-bound job faster but costs proportionally more per minute — worth it only if your job actually parallelises across cores; a 16-core runner that runs a single-threaded build just bills 8× for nothing and sits idle. And cache restore time is not free: restoring a multi-hundred-MB cache over the network can cost more than the rebuild it saves, so cache the slow-to-produce things (deps, compiled output), not everything.