Table of contents
- Quick read
- Readiness check
- List what the cache actually stores
- Key the cache to inputs that change behavior
- Set the invalidation and purge rule
- Measure hit rate and rebuild cost
- Protect secrets and artifacts in the cache
- Prove a cold build on a schedule
- Review the cache when dependencies change
- Role brief
- Frequently asked questions
- Sources
Is the handoff ready?
Use these checks before access expands or the first ticket begins.
Inventory
Ready: List each cache, its tool, owner, size, and retention.
Needs work: The lane has no written record for this check.
Key inputs
Ready: Record lockfile, toolchain, flags, image, and branch scope.
Needs work: The lane has no written record for this check.
Purge rule
Ready: Name the triggers, the operator, and the jobs to rerun.
Needs work: The lane has no written record for this check.
Cold build
Ready: Schedule and log a cache-disabled build with its duration.
Needs work: The lane has no written record for this check.
List what the cache actually stores
List every cache the pipeline uses, including package downloads, compiler output, test fixtures, and container layers. Record the tool, the storage location, and the person who can purge it. Note the size limit and the retention policy for each cache. A cache that nobody has listed cannot be invalidated on purpose.
Separate a cache that only saves time from a cache that changes the build result. Record the caches that contain generated code, environment-specific binaries, or credentials. Mark those as sensitive and give them a stricter key and purge rule. A cache that silently changes output is a correctness risk, not a speed feature.
Key the cache to inputs that change behavior
Write the key from the lockfile, the toolchain version, the build flags, and the operating-system image. Record which inputs the key covers and which it deliberately ignores. Note the branch or environment scope so a production build never restores a test cache. A key built only from the branch name will serve a stale compiler after an upgrade.
Record the fallback order when an exact key is missing, such as a restore key that matches the lockfile prefix. Note the risk that a partial match restores incompatible output. Set the rule for when the pipeline must rebuild instead of restoring. A fallback that quietly uses an older cache hides the very change the build was testing.
Set the invalidation and purge rule
Write the triggers that force a clean cache, such as a toolchain upgrade, a lockfile change, or a corrupted artifact report. Record who can purge the cache and how the purge is announced. Note the jobs that must rerun after a purge. An invalidation that happens only when someone remembers is not a rule.
Record the maximum age for each cache and the cleanup job that enforces it. Note the storage cost and the effect on the slowest job. Keep the purge command in the pipeline documentation. A cache with no age limit grows until quota or cost forces an emergency cleanup.
Measure hit rate and rebuild cost
Record the cache hit rate for each job and the time saved per hit. Note the jobs whose hit rate is low because the key changes too often. Compare the saved time with the cost of storing and restoring the cache. A cache that saves seconds but costs minutes to download is a net loss.
Record the cold-build duration and the warm-build duration on the same runner class. Note the variance across runs and the jobs that dominate the total. Use the cold number to set the timeout and the patience of the team. A pipeline tuned only to warm builds will time out on the day the cache is empty.
Protect secrets and artifacts in the cache
Check that no cache contains tokens, credentials, or customer data from a test run. Record the scan that looks for secrets and the owner who responds to a finding. Note the caches that are shared across repositories or teams. A poisoned or leaky cache spreads farther than the job that created it.
Record which build artifacts must never come from a cache, such as a signed release or a published container image. Note the step that re-creates the artifact from source for a release. Keep the provenance record for the artifact that ships. A release is not reproducible when its binary came from an untrusted cache.
Prove a cold build on a schedule
Run a scheduled cold build with the cache disabled and record the result. Note the duration, the failing step, and the dependency that was only present in the cache. Fix the pipeline rather than the cache when the cold build fails. A cold build that nobody runs is discovered during an incident.
Record the date of the last cold build and the owner who reviewed it. Note the jobs excluded from the test and the reason. Keep the cold-build log beside the cache configuration. The evidence should show that the pipeline can rebuild the product from source alone.
Review the cache when dependencies change
Review the keys when a package manager, compiler, or base image changes. Record the new input and the date the key changed. Purge the old cache and run the cold build against the new toolchain. A key that was correct last quarter may restore incompatible output after an upgrade.
Review the cache list when a new service or job joins the pipeline. Record the new cache, its owner, and its size budget. Note the jobs that share a key by mistake. The review keeps the cache inventory aligned with the pipeline it serves.
Copy-ready brief
Put the operating agreement in writing.
Separate speed-only caches from caches that can change the build result.
Include the lockfile, toolchain, build flags, and runner image.
Scan for secrets and never restore a signed release from cache.
Keep the cold-build log and the date of the last review.
Frequently asked questions
Is a high hit rate always good?
No. A high rate on a stale key can hide a toolchain change, so pair the metric with a cold-build check.
Who should be allowed to purge the cache?
A named pipeline owner with a recorded reason, because an unexplained purge slows every team that shares it.
Can release artifacts come from the cache?
No. Rebuild and sign the release from source, then record the provenance of the shipped artifact.
How often should the cold build run?
At least once per release cycle and after any change to the cache key or the runner image.
Sources
- GitHub Actions dependency caching
Cache keys, restore keys, and scope behavior.
- Docker build cache
Layer cache invalidation and cache backends.
- npm ci
Clean installs from a lockfile for reproducible dependency state.
- Turborepo caching
Task hashing and remote cache inputs.
