iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Your local Docker build cache belongs to your local BuildKit builder; a separate or short-lived CI builder does not inherit it automatically. To reuse cache in CI, configure the build to export cache to storage that survives between runs and import that cache on the next build. Docker documents this as the external-cache pattern for CI/CD.
Why doesn’t Docker reuse my build cache in CI?
BuildKit keeps an internal cache on the builder that performed the build. Your laptop’s builder and the builder used by CI are usually separate, and CI jobs often start in fresh environments. That means a fast local build is not evidence that the CI builder has access to the same cache.
Docker’s cache storage backends documentation explains that external caches must be explicitly exported and imported. A CI workflow therefore needs both a cache destination on one build and a matching cache source on a later build. If the workflow does not preserve the builder itself, relying only on its internal cache will not carry cache state between runs.
How to diagnose a cache that is missing in CI
- Identify the CI builder. Check which Buildx builder or build action runs the build, and whether that builder persists across jobs and runs. If each run gets a fresh builder, its internal cache starts without the previous run’s state.
- Check for both cache settings. Inspect the actual build command or action configuration. It needs an export setting (
--cache-toor an action’scache-to) and an import setting (--cache-fromorcache-from). Docker describes these as explicit operations for external cache backends. - Verify the backend and reference. The backend type and storage location used to export must correspond to a location the next build imports. For a registry cache, check that the reference is stable and that CI credentials can read and write it.
- Check cache scope and permissions. Branches or workflow events may not have access to the same cache. If you want isolated branch caches, use different storage references; exporting to the same location overwrites its prior contents. A build can import more than one cache, for example a branch cache and a main-branch cache.
- Read the build logs for export and import errors. A configured cache can still fail to load or save. For GitHub Actions, check workflow context, permissions, driver compatibility, and possible API throttling if cache operations fail or time out.
- Decide whether the cache is useful for your build. A cache can be successfully imported yet miss steps that matter. Choose
minormaxmode based on whether caching intermediate build stages is important.
Which cache backend should you use?
The right backend depends on whether your builder supports it, whether the cache survives between runs, how your CI system controls access, whether you publish the image, and whether you need intermediate-stage cache. Docker lists several external backends; the trade-offs below help narrow the choice.
#1 Best Overall
| Backend | Best fit | Trade-offs and requirements |
|---|---|---|
gha |
GitHub Actions workflows that fit GitHub’s cache service limits. | Docker recommends it for this context but marks it experimental. Access rules and authentication are workflow-specific, and frequent lookups may encounter API throttling. With the default docker driver, the containerd image store is required; otherwise use a compatible alternative driver. Check Docker’s GitHub Actions cache backend documentation for current requirements. |
inline |
A simple workflow that pushes an image and wants cache metadata carried with it. | Supports only min mode, so it is less suitable when cache for intermediate steps in a complex multi-stage build matters. See Docker’s inline cache documentation. |
registry |
A workflow that uses a registry and needs a separate cache reference or max mode. |
Requires registry access and a dedicated cache image reference. Use distinct references when you need separate branch or image scopes, since writing to the same location replaces its existing cache data. See Docker’s registry cache documentation. |
local |
Testing or CI that can persist or restore a filesystem directory between runs. | The directory must actually survive between jobs or be restored by the workflow. Repeated exports can leave old blobs behind; Docker documents reset=true for Buildx 0.35.0 and later. See the local cache documentation. |
How to configure a registry cache with Buildx
A registry cache is a practical option when CI already pushes images to a registry and you want cache storage separate from the image. The following pattern imports from and exports to the same cache reference, using max mode to include intermediate build steps:
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 example references with your image and cache locations, and ensure the CI identity can read and write the cache reference. Docker’s registry backend guidance documents this export/import pattern. If separate branch caches are needed, give them separate references rather than having each branch overwrite the same cache.
How to configure the GitHub Actions cache backend
For GitHub Actions, Docker’s documented build-push-action example uses type=gha for both import and export:
- 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=maxDocker’s example says the action supplies the cache URL and token automatically. If you invoke Buildx directly in workflow steps instead, make sure the required cache-service values are available in that workflow context. Confirm that the action version and backend requirements still match your workflow and Buildx driver.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to use min versus max
The cache mode determines how much build cache is exported. Docker’s backend documentation describes min as keeping layers included in the final image and max as also including intermediate build steps.
- Choose
minwhen smaller exports and faster transfers matter more, or when caching intermediate stages is unlikely to help. - Choose
maxwhen intermediate stages are expensive to rebuild and extra cache storage or transfer is acceptable.
There is no universal best mode: compare cache hits and transfer behavior for your actual build. Inline cache supports only min; choose a backend such as registry when you need max.
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.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute
