Run a scheduled job that installs from your lockfiles on the default branch and saves the cache inside every 7 day eviction window, then run it again right before a release or freeze lift. Warm your mirror the same way, so a burst of builds reads from your copies instead of the public registry.
Why warm at all
A release is when many builds start at once. If every runner starts cold, each one downloads the same packages, and the registry sees a spike that looks like abuse. You may hit rate limits, slow responses or errors at the worst moment. A warm cache turns that spike into local reads.
There are two caches to warm, and they fail differently:
- The runner side cache, such as the CI provider's dependency cache.
- The mirror or pull-through cache, which holds packages and images for all runners.
What you need to know about the CI cache
GitHub's documentation gives the rules that shape a warming job. Entries not accessed for over 7 days are removed. When a repository passes its size limit, entries are evicted oldest access first. The key matching works in order: an exact key is a hit, and otherwise the restore keys are tried in sequence for prefix matches, and the most recently created match is returned. The same page notes that when no match is found on a feature branch, the cache action retries on the default branch, subject to scope restrictions. A cache that already exists cannot be changed.
Two practical points follow. A cache saved on the default branch can serve feature branches, so that is the right place to warm. And because entries cannot be edited, "warming" means creating a fresh entry under a new key when the lockfile changes.
The plan
- Schedule a warm job on the default branch. Run it at least every few days so no entry reaches 7 days without access. Use a cron trigger.
- Install from the lockfile. Use the strict install command for your tool so the warm cache matches what real builds use. See frozen lockfile flags.
- Key on the lockfile hash. When the lockfile changes in a merge, the next warm run creates the new entry.
- Warm the mirror too. Request the packages and base images through the mirror so it stores them. For container images see mirror Docker Hub images with a pull-through cache.
- Trigger a manual warm before a freeze lift. One run the evening before is enough for most teams.
- Check hit rates. After the burst, compare cache hit rate and registry error counts with a normal day. If the warm job did its work, errors stay flat.
What not to do
- Do not warm from a branch that runs untrusted code. A cache that other jobs trust should be written by trusted workflows only. See GitLab CI cache, protected vs unprotected branches for the same idea in another system.
- Do not set restore keys so loose that an old, unrelated cache restores. That is covered in restore keys and stale dependency caches.
- Do not warm by raising retry counts. That moves the flood from the cache to the registry.
How to know it worked
| Signal | Cold start | Warmed |
|---|---|---|
| Dependency step time | Long and uneven | Short and steady |
| Registry error rate during the burst | Spikes | Flat |
| Requests to the public registry | Many per job | Few, mostly misses |
Where Safeguard fits
A warmed cache is a fixed set of packages that many builds trust. Safeguard's SBOM and dependency scanning checks that set, and policies and gates keep a newly warmed lockfile from shipping with known critical issues.
Quick check
How often should a warm job run?
At least once inside each 7 day window for a cache you rely on, plus a manual run before a release or freeze lift.
Can I edit an existing cache entry?
No. GitHub's docs say the contents of an existing cache cannot be changed. Create a new entry under a new key instead.
Sources
Last reviewed: 19 October 2026.
