Caching & Matrix Builds

## The lookup, step by step A typical dependency cache looks like this: - uses: actions/cache@v4 id: npm-cache with: path: ~/.npm key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-npm- When the step runs: 1. **Exact match on `key`.** If an entry with precisely that key is visible to this run, its archive is extracted to `path`, and the step sets `cache-hit` to `'true'`. Because the entry already holds what this key describes, the action does **not** save anything in its post step. 2. **No exact match.** Each entry in `restore-keys` is tried in order as a **prefix**. The most recently created entry whose key starts with that prefix is restored. Files land on disk, but `cache-hit` is `'false'` — it reports exact hits only. 3. **Nothing matched.** Nothing is restored; the job installs from scratch. In cases 2 and 3, if the job succeeds, the action's post step archives `path` and saves it under the exact `key`. ## Why the two-part design The key is a content fingerprint. `hashFiles('**/package-lock.json')` returns a SHA-256 over the matched files, so the key changes exactly when the dependency set changes — correctness. The restore-keys are a stable prefix, so a lockfile bump still restores the previous cache and the package manager only downloads what actually changed — speed. Without restore-keys, every lockfile edit means a cold install; without a hashed key, the cache would never be refreshed at all. Order matters and should run from most to least specific: restore-keys: | ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }} ${{ runner.os }}-npm- Include `runner.os` (or the matrix's OS value) in the prefix. Caches restored across operating systems are usually useless and sometimes actively broken, since native modules and paths differ. ## `cache-hit` and conditional steps `cache-hit` is a string, so compare it as one: - if: steps.npm-cache.outputs.cache-hit != 'true' run: npm ci A frequent bug is skipping the install on any restore, including a partial one — that leaves a stale `node_modules` that does not match the lockfile. The safe pattern is to cache the package manager's download directory rather than the installed tree, and always run the install; with a warm cache it is fast and it reconciles the difference. ## Immutability Cache entries are write-once. If the key already exists, the save is a no-op (the log says the cache already exists with that key). You cannot refresh a cache in place — the key must change to produce a new entry. This is why a hardcoded key such as `npm-cache` yields a permanently frozen cache, and why keys are built from a hash of whatever determines the content. ## Scope and lifetime Caches are scoped to a branch. A run can restore entries created on its own ref, and — for a pull request — on the base branch, plus entries from the repository's default branch; it cannot read a sibling feature branch's caches. This isolation is a security property, not an oversight: it stops a branch from poisoning another branch's build inputs. Entries also expire, and a repository has a total cache size budget with least-recently-used eviction when it is exceeded, so a warm cache is a best-effort optimisation and never a correctness dependency. ## Splitting restore and save `actions/cache/restore` and `actions/cache/save` let you separate the two halves — for example, restoring early, and saving only on the default branch so pull-request runs consume the cache without filling the budget with short-lived entries. Useful inputs on the main action include `fail-on-cache-miss` and `lookup-only`. ## The one-sentence answer "`key` is the exact identity and the save name; `restore-keys` are fallback prefixes tried on a miss, giving a warm start without ever preventing the cache from being refreshed."