buildx/docs/guides/cache/gha.md

GitHub Actions cache storage

Warning

The gha cache is currently experimental. You can use it today, in current releases of Buildx and Buildkit, however, the interface and behavior do not have any stability guarantees and may change in future releases.

The gha cache utilizes the GitHub-provided Action's cache available from inside your CI execution environment. This is the recommended cache to use inside your GitHub action pipelines, as long as your use case falls within the size and usage limits set by GitHub.

Note

The gha cache storage backend requires using a different driver than the default docker driver - see more information on selecting a driver here. To create a new docker-container driver (which can act as a simple drop-in replacement):

docker buildx create --use --driver=docker-container

If you're using the official docker/setup-buildx-action, then this step will be automatically run for you.

To import and export your cache using the gha storage backend we use the --cache-to and --cache-from flags configured with the appropriate Authentication parameters:

$ docker buildx build --push -t <user>/<image> \
  --cache-to type=gha,url=...,token=...
  --cache-from type=gha,url=...,token=...

By default, caches are scoped by branch - this ensures a separate cache environment for the main branch, as well as for each feature branch. However, if you build multiple images as part of your build, then caching them both to the same gha scope will overwrite all but the last build, leaving only the final cache.

To prevent this, you can manually specify a cache scope name using the scope parameter (in this case, including the branch name set by GitHub to ensure each branch gets its own cache):

$ docker buildx build --push -t <user>/<image> \
  --cache-to type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image
  --cache-from type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image
$ docker buildx build --push -t <user>/<image2> \
  --cache-to type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image2
  --cache-from type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image2

GitHub's cache scoping rules, still apply, with the cache only populated from the current branch, the base branch and the default branch for a run.

Authentication

To authenticate against the GitHub Actions Cache service API to read from and write to the cache, the following parameters are required:

• url: cache server URL (default $ACTIONS_CACHE_URL)
• token: access token (default $ACTIONS_RUNTIME_TOKEN)

If the parameters are not specified, then their values will be pulled from the environment variables. If invoking the docker buildx command manually from an inline step, then the variables must be manually exposed, for example, by using crazy-max/ghaction-github-runtime as a workaround.

With docker/build-push-action

When using the docker/build-push-action, the url and token parameters are automatically populated, with no need to manually specify them, or include any additional workarounds.

For example:

      -
        name: Build and push
        uses: docker/build-push-action@v3
        with:
          context: .
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

Cache options

The gha cache has lots of parameters to adjust its behavior.

Cache mode

See Registry - Cache mode for more information.

Further reading

For an introduction to caching see Optimizing builds with cache management.

For more information on the gha cache backend, see the BuildKit README.