How to Cache Docker Layers to a Registry With buildx

type=registry pushes layer cache to a dedicated image ref so any runner can pull it, unbound by the CI cache quota.

Point cache-to: type=registry,ref=... at a cache image and cache-from: type=registry,ref=... at the same ref. Cache lives in your registry, so it is shared across runners, repos, and self-hosted fleets.

Steps

• Log in to the registry before building.
• Set cache-to to a distinct cache tag, not the app image tag.
• Set cache-from to the same ref to restore on the next run.

Workflow

steps:
  - uses: docker/setup-buildx-action@v3
  - uses: docker/login-action@v3
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}
  - uses: docker/build-push-action@v6
    with:
      context: .
      push: true
      tags: ghcr.io/acme/app:latest
      cache-from: type=registry,ref=ghcr.io/acme/app:buildcache
      cache-to: type=registry,ref=ghcr.io/acme/app:buildcache,mode=max

Gotchas

• Registry cache is not subject to the 10 GB per-repo GitHub cache limit.
• Use a separate cache tag so pushes do not overwrite your runnable image.

Related guides