How to Use a Pull-Through Cache Registry in CI

A pull-through cache mirror serves base images from a nearby cache, sparing you Docker Hub rate limits.

Point BuildKit at a registry mirror using a buildkitd.toml config passed to docker/setup-buildx-action. Pulls of cached images are served from the mirror.

Steps

Stand up a pull-through cache (for example a registry running in mirror mode).
Create a buildkitd.toml that lists the mirror under [registry."docker.io"].
Pass it via buildkitd-config on docker/setup-buildx-action.

buildkitd config

buildkitd.toml

[registry."docker.io"]
  mirrors = ["mirror.internal.example.com"]

[registry."mirror.internal.example.com"]
  http = false

Workflow

.github/workflows/ci.yml

steps:
  - uses: docker/setup-buildx-action@v3
    with:
      buildkitd-config: ./buildkitd.toml

Gotchas

A mirror caches public images; private images still authenticate against the upstream.
Mirrors reduce pulls but do not remove the need for authenticated pulls on Docker Hub.