Caching, matrix builds and artifacts

Caching: a lockfile hash is the only safe key

When you see a CI run spend three minutes just installing packages, that is a cache waiting to be configured — or, worse, a broken cache that never invalidates. Here is how to get it right.

Each CI job runs on a clean machine, so without help it redoes every expensive, deterministic step — chiefly the dependency install — from zero on every run. actions/cache fixes this by saving a directory after the first run and restoring it on later runs, keyed on a string you choose. The cardinal rule lives entirely in that key: it must change exactly when the cached contents should change, and not before. For dependencies, the input that determines node_modules is the lockfile, so you hash it.

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

hashFiles('**/package-lock.json') produces a checksum that changes the instant any dependency changes. On a hit, the cache restores and the install is near-instant; on a miss — a new lockfile — the key is new, so the old entry is not reused, you install fresh, and the run saves a new entry under the new key. That is why a constant key: deps is dangerous: it can never miss, so it restores stale dependencies forever and your new lockfile is silently ignored. Always bind the key to the content.

restore-keys is the fallback ladder. When the exact key misses, GitHub tries each prefix in turn and restores the most recent partial match — so a lockfile bump still seeds the cache from the previous runner.os-npm- entry instead of starting empty, and the package manager only downloads the delta. It is a warm start, not a correctness shortcut: the exact key still governs whether the entry is treated as current.

Matrix: one job definition, many parallel runs

How do you prove your library works on Node 18, 20, and 22 without writing three nearly-identical jobs? That is the exact problem strategy.matrix solves.

A strategy.matrix runs the same job once per combination of the dimensions you list — the standard way to prove your code works across Node versions and operating systems without copy-pasting jobs. GitHub expands the cartesian product and schedules every combination in parallel.

test:
  strategy:
    fail-fast: false
    max-parallel: 4
    matrix:
      node: [18, 20, 22]
      os: [ubuntu-latest, macos-latest]
      include:
        - { node: 22, os: ubuntu-latest, coverage: true }
      exclude:
        - { node: 18, os: macos-latest }
  runs-on: ${{ matrix.os }}
  steps:
    - uses: actions/setup-node@v4
      with: { node-version: ${{ matrix.node }} }

That node × os grid is 3 × 2 = 6 jobs; the exclude drops one, the include adds an extra field to one existing combination (and, with a new value, could add a whole job). fail-fast: true (the default) cancels every sibling the moment one fails — fast feedback, but you lose the full picture; set it false when you need to see which combinations broke. max-parallel caps how many run at once, throttling concurrent runner usage. Mind the explosion: dimensions multiply, so adding a third 3-value axis turns 6 jobs into 18, each consuming runner minutes — a matrix is a cost dial, not a free coverage win. Together, these knobs let you get full cross-version signal in one workflow definition; without fail-fast: false, a single broken Node 18 cell can mask three other failing combinations hiding beneath it.

Artifacts: hand output from one job to the next

Because every job is a fresh machine, a build produced in one job does not exist in the next — the filesystem is gone when the job ends. The cache is the wrong tool here: it is a keyed, best-effort, possibly-evicted speedup, not a guaranteed handoff. Artifacts are the right tool — explicit, durable-for-the-run outputs you upload and later download, and that you can also publish as the run’s deliverables (a built bundle, test reports, coverage).

build:
  steps:
    - run: npm run build
    - uses: actions/upload-artifact@v4
      with: { name: dist, path: dist/ }
deploy:
  needs: build
  steps:
    - uses: actions/download-artifact@v4
      with: { name: dist }
    - run: ./deploy.sh dist/

Build once, deploy the exact same bytes you tested — no rebuild drift between jobs. Artifacts have a retention period (default 90 days, configurable) and count against storage, so name them deliberately and keep large ones short-lived.