Build caching in CI: keys, restore fallbacks and cache poisoning

Goal

Cut pipeline time by reusing dependency downloads and image layers without letting the cache change build results or become a route for injecting code.

Prerequisites

Lockfiles for every package manager in the repository; a Dockerfile ordered so that dependency installation precedes source copying; a CI system with a cache action or a registry reachable from the builder.

Steps

1. Key dependency caches on the operating system plus a hash of the lockfile (${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}), and list restore-keys from most to least specific so a lockfile change restores the nearest older cache instead of starting cold. The cited GitHub reference describes exact-match first, then partial matches, then the restore keys in order.
2. Understand scope: the same reference states that a run can restore caches from its own branch or the default branch (and the base branch for pull requests), never from sibling or child branches. Warm the default branch cache on merge so feature branches inherit it.
3. Cache the package manager's download directory rather than the installed tree unless the install is a pure function of the lockfile.
4. For images, export the BuildKit cache explicitly: the cited backends page notes that unlike the always-on local cache, external backends must be exported with --cache-to and imported with --cache-from; use type=registry with mode=max to keep intermediate stages, and import both the branch cache and the main cache.
5. Order Dockerfile instructions from rarely to frequently changed, as the cited invalidation page recommends, because invalidating one layer invalidates everything after it; the page also states that COPY checksums ignore mtime.
6. Never write secrets or tokens into cached paths: the GitHub reference states cache contents are not signed or verified and that anyone able to open a pull request can read base-branch caches. Restrict cache writes to trusted triggers (push, schedule) and keep untrusted-trigger workflows read-only.
7. Watch eviction: the reference gives a default of 10 GB per repository and removal of entries not accessed in 7 days; oversized caches thrash.
8. Rebuild without cache on a schedule (--no-cache, or a key with a date component) to catch dependency drift hidden by a warm cache.

Expected result

A cache hit on unchanged lockfiles; a near hit after a small lockfile change; identical build outputs with or without cache; no path in the cache that a fork pull request can poison for a privileged run.

Limits and test basis

Cache benefit depends on network speed relative to install time and is not claimed as a number. Mechanics follow the cited GitHub and Docker documentation; other CI systems scope and evict differently.