13.1.3.1 Pipeline Local Cache
A focused guide to Pipeline Local Cache, connecting core concepts with practical Docker and container operations.
Pipeline local cache refers to a CI runner's own, potentially already-present local Docker layer cache, available specifically on self-hosted or persistent runners that aren't recreated fresh for every job, in contrast to the more common, fully ephemeral hosted runner scenario.
When a Local Cache Is Actually Available
A self-hosted CI runner, reused across multiple pipeline runs rather than provisioned fresh each time, can retain a local Docker layer cache between those runs without any additional, explicit cache persistence configuration.
docker build -t myapp .
On a persistent, reused self-hosted runner, this build can benefit from layers cached during a previous run on that same runner, without needing a registry-based cache or other explicit persistence mechanism.
Why Hosted, Ephemeral Runners Generally Don't Have This Benefit
A hosted CI runner, freshly provisioned for each job and discarded afterward, has no local cache to benefit from at all — this is precisely why registry-based or platform-native caching mechanisms become necessary in that more common context.
docker build -t myapp .
The exact same command, run on a fresh hosted runner, gets no caching benefit at all, unlike the persistent self-hosted scenario.
Trade-offs Between Self-Hosted Runners and Hosted, Ephemeral Ones
While self-hosted, persistent runners can offer this local caching benefit, they also introduce their own maintenance burden and potential for environment drift between runs — a trade-off worth weighing against simply configuring explicit cache persistence on a more conveniently managed hosted runner.
docker system df
Monitoring a self-hosted runner's accumulated disk usage from this local cache over time is an additional operational consideration this approach introduces.
Combining Local Caching With Periodic Cache Cleanup
A persistent runner's local cache, left entirely unmanaged, can grow indefinitely — periodically pruning it keeps disk usage reasonable.
docker system prune -af --filter "until=168h"
Why Pipeline Local Cache Matters
Understanding when a local cache is genuinely available (persistent, self-hosted runners) versus when it isn't (ephemeral, hosted runners) clarifies why explicit cache persistence configuration is necessary in the more common hosted scenario, while also informing the trade-offs involved in choosing a self-hosted runner setup specifically for this caching benefit.