How to Cache Docker Layers With the buildx gha Backend

buildx can read and write BuildKit layer cache to the GitHub Actions cache service via type=gha.

With docker/build-push-action, set cache-from: type=gha and cache-to: type=gha,mode=max. BuildKit then stores and restores layer cache through the same backend that actions/cache uses.

Steps

• Set up buildx with docker/setup-buildx-action.
• Add cache-from: type=gha and cache-to: type=gha,mode=max.
• Use mode=max to also cache intermediate stage layers.

Workflow

steps:
  - uses: actions/checkout@v4
  - uses: docker/setup-buildx-action@v3
  - uses: docker/build-push-action@v6
    with:
      context: .
      push: false
      cache-from: type=gha
      cache-to: type=gha,mode=max

Gotchas

• The gha backend counts against the same 10 GB repo cache budget as other caches.
• mode=min caches only the final image layers, which restores less but stays smaller.

Related guides