The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Your local Docker build is fast because its BuildKit builder retains a cache on your machine. CI usually runs on a separate, short-lived builder, so it cannot see that local cache—and a fresh runner may have no cache from an earlier job either. To reuse build cache in CI, configure the build to export it to storage that persists and import it on the next run.
Why doesn’t Docker reuse my build cache in CI?
BuildKit keeps an internal cache with the builder that created it. Your laptop’s builder and the builder running a CI job are separate, so the laptop’s cache is not automatically available to CI. If CI provisions a clean environment for each run, its own internal cache may also disappear between runs. Docker recommends external cache storage for importing cache into later builds: Cache storage backends.
As an Amazon Associate I earn from qualifying purchases.
External caching is explicit: the build must export cache with --cache-to (or the equivalent action setting) and import it with --cache-from. Without both ends configured, a successful build can still leave the next CI run with nothing to reuse.
Diagnose the cache miss before changing the workflow
- Check builder persistence. Identify which Buildx builder the CI job uses and whether it survives between runs. A new runner or builder will not inherit the developer’s internal cache.
- Check both cache directions. Inspect the actual Buildx command or action inputs for a cache export and a matching import source. Confirm that the export completed and that the next run reads from the same backend.
- Check the reference and scope. For registry or local caches, verify the type and reference or path match. Ensure CI credentials can read and write the target. If branches or images need separate caches, give them distinct locations; writing to the same location overwrites its prior contents. You can import more than one cache, such as a branch cache and a main-branch cache.
- Read the build logs. Look for cache import or export errors, then distinguish a failed transfer from a valid cache that simply has no matching layers. A cache is useful only when the build steps and inputs match what was cached.
- Review the cache mode and CI limits.
minexports layers used in the final image;maxalso includes intermediate build steps. The latter may create more cache hits, but increases storage and transfer. Frequent cache operations can also encounter service throttling.
Choose a cache backend that CI can actually reach
| Backend | When it fits | Important trade-off |
|---|---|---|
gha |
GitHub Actions workflows using GitHub’s cache service. | Docker marks it experimental. It has workflow access and service limits, and the default docker driver requires the containerd image store; check current compatibility and limits in Docker’s GitHub Actions cache documentation. |
inline |
A straightforward workflow that pushes an image and wants its cache metadata carried with that image. | Supports only min mode, so it is less suitable when intermediate stages matter. See Docker’s inline cache documentation. |
registry |
A workflow with registry access that needs a separate cache reference or max mode. |
Requires a dedicated cache image reference and registry read/write access. Use distinct references for independently scoped caches to avoid overwrites. See Docker’s registry cache documentation. |
local |
A workflow that can persist or restore a filesystem directory between runs. | The path must actually survive between jobs or be restored. Repeated exports can leave old blobs behind; Docker documents reset=true for Buildx 0.35.0 and later. See Docker’s local cache documentation. |
Choose based on the builder’s backend support, persistence, branch and event access, registry or CI credentials, and the balance between cache hits and transfer overhead. Docker describes min as generally smaller and quicker to transfer, while max can produce more hits by retaining intermediate layers; the useful choice depends on the build.
#1 Best Overall
Configure an external cache
Buildx with a registry cache
Use a stable registry reference for the cache, separate from the final image reference if you want independent storage. This example pushes the image and imports and exports a maximum-mode cache:
docker buildx build --push -t <registry>/<image>
--cache-from type=registry,ref=<registry>/<cache-image>
--cache-to type=registry,ref=<registry>/<cache-image>,mode=max .Replace the angle-bracketed values with your registry and image names, and make sure the CI identity can read and write both references. Docker documents the registry backend and its cache modes at registry cache configuration.
GitHub Actions with build-push-action
For GitHub Actions, Docker’s documented action pattern is:
Recommended Free Tools
- name: Build and push
uses: docker/build-push-action@v7
with:
context: .
push: true
tags: <registry>/<image>:latest
cache-from: type=gha
cache-to: type=gha,mode=maxThe documentation’s example uses action version v7; verify the version appropriate to your workflow. The action supplies the cache URL and token automatically. A manually invoked Buildx command in a workflow step may need the relevant GitHub cache service variables exposed instead. Also check driver compatibility, branch or event permissions, and service throttling if cache operations fail or time out. See Docker’s GitHub Actions cache guidance.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
