What Is a Runner Cache? Reusing Work Across Clean Runs
A runner cache stores expensive artifacts - dependencies, build outputs, Docker layers - outside the runner so a fresh, ephemeral machine can restore them instead of rebuilding from scratch.
Ephemeral runners are clean but have nothing cached, so every job would reinstall dependencies and rebuild from zero. A runner cache solves that: keep the expensive bits in external storage and restore them onto each fresh runner.
Why caching is needed
A clean runner pays a full dependency-install and build tax every job. For a large project that can dwarf the actual test time. Caching restores the heavy, slow-changing parts so the job spends its time on real work.
What gets cached
- Package manager downloads (npm, pip, Maven, Cargo).
- Compiled build outputs and incremental build state.
- Docker image layers to avoid rebuilding unchanged stages.
Cache without dirty state
The key distinction: a runner cache restores known artifacts onto a clean machine, which is safe. Reusing a whole dirty runner is unsafe. Caching gives you speed while keeping the correctness of ephemeral runners.
Caching on managed runners
Managed platforms ship fast, integrated caching so ephemeral runners restore dependencies and layers quickly. Latchkey pairs warm pools with built-in caching so fresh runners are also fast runners.
Cache keys and invalidation
A cache is keyed on something that captures its inputs - typically a hash of the lockfile or Dockerfile. When the inputs change the key changes and the cache is rebuilt; when they do not, it is restored. A poorly chosen key either misses constantly or serves stale artifacts, so the key is as important as the cache itself.
Key takeaways
- A runner cache stores deps and build outputs outside the runner.
- It lets ephemeral machines skip rebuilding from scratch.
- It restores known artifacts onto clean runners, keeping correctness.
- Managed caching makes fresh runners fast without reusing dirty state.