13.1.3.2 Pipeline Registry Cache

Pipeline registry cache uses a container registry as the storage location for Docker's build cache, pushing and pulling dedicated cache layers to and from that registry, providing a persistent caching mechanism that works regardless of which specific ephemeral CI runner instance happens to execute a given build.

Configuring a Registry-Based Cache

BuildKit supports exporting and importing cache directly to and from a registry, separate from the actual application image being built.

docker buildx build \
  --cache-from type=registry,ref=registry.example.com/myapp:buildcache \
  --cache-to type=registry,ref=registry.example.com/myapp:buildcache,mode=max \
  -t registry.example.com/myapp:${{ github.sha }} \
  --push .

The --cache-to flag pushes an updated cache after this build; the --cache-from flag pulls the existing cache before starting, regardless of which runner instance executes either step.

Why mode=max Captures More Caching Opportunity

The default caching mode only caches layers that end up in the final image, while mode=max additionally caches intermediate layers from earlier build stages, providing more caching opportunity for multi-stage builds specifically.

--cache-to type=registry,ref=myapp:buildcache,mode=max

This matters particularly for multi-stage Dockerfiles, where intermediate build-stage layers wouldn't otherwise be captured by the more limited default caching mode.

Why a Dedicated Cache Tag Keeps Things Organized

Using a clearly named, dedicated tag (like buildcache) for this purpose, separate from actual application version tags, keeps the registry's purpose-built cache artifacts clearly distinguished from genuinely deployable images.

docker images registry.example.com/myapp

myapp:buildcache       (cache artifact, not deployable)
myapp:1.4.2            (actual deployable release)

Why Pipeline Registry Cache Matters

A registry-based cache provides a reliable, persistent caching mechanism for CI builds that works correctly regardless of runner ephemerality, making it one of the more broadly applicable approaches for meaningfully speeding up containerized CI/CD pipelines.