GitHub Actions cache

The GitHub Actions cache utilizes the GitHub-provided Action's cache or other cache services supporting the GitHub Actions cache protocol. This is the recommended cache to use inside your GitHub Actions workflows, as long as your use case falls within the size and usage limits set by GitHub.

This cache storage backend works with the default docker driver only when the containerd image store is enabled. If the containerd image store isn't enabled, use a different driver. See Build drivers for more information.

Synopsis

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha[,parameters...] \
  --cache-from type=gha[,parameters...] .

The following table describes the available CSV parameters that you can pass to --cache-to and --cache-from.

Authentication

If the url, url_v2 or token parameters are left unspecified, the gha cache backend will fall back to using environment variables. If you invoke the docker buildx command manually from an inline step, then the variables must be manually exposed. Consider using the crazy-max/ghaction-github-runtime, GitHub Action as a helper for exposing the variables.

Scope

Scope is a key used to identify the cache object. By default, it is set to buildkit. If you build multiple images, each build will overwrite the cache of the previous, leaving only the final cache.

To preserve the cache for multiple builds, you can specify this scope attribute with a specific name. In the following example, the cache is set to the image name, to ensure each image gets its own cache:

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

GitHub's cache access restrictions, still apply. Only the cache for the current branch, the base branch and the default branch is accessible by a workflow.

Cache writes also depend on the workflow's cache access. Some events receive read-only access in the default-branch context. See Cache write restrictions for affected triggers and how to configure cache imports and exports.

Version

If you set version explicitly, BuildKit uses that version. Otherwise it selects the version from the cache server URL:

• Setting url_v2 selects v2.
• Otherwise a url that points at the v2 cache service (results-receiver.actions.githubusercontent.com) selects v2, and any other url selects v1.

Inside a workflow, Buildx fills unspecified URL parameters from the environment. It sets url_v2 from $ACTIONS_RESULTS_URL when you pass version=2, or when you omit version and $ACTIONS_CACHE_SERVICE_V2 holds a true value such as 1 or true. It sets url from $ACTIONS_CACHE_URL, falling back to $ACTIONS_RESULTS_URL when $ACTIONS_CACHE_URL isn't set.

Only one URL applies to a build. With v2, BuildKit uses url_v2, falling back to url when url_v2 isn't set. With v1, it uses url.

Using docker/build-push-action

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

For example:

- 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=max

Avoid GitHub Actions cache API throttling

GitHub's usage limits and eviction policy causes stale cache entries to be removed after a certain period of time. By default, the gha cache backend uses the GitHub Actions cache API to check the status of cache entries.

The GitHub Actions cache API is subject to rate limiting if you make too many requests in a short period of time, which may happen as a result of cache lookups during a build using the gha cache backend.

#31 exporting to GitHub Actions Cache
#31 preparing build cache for export
#31 preparing build cache for export 600.3s done
#31 ERROR: maximum timeout reached
------
 > exporting to GitHub Actions Cache:
------
ERROR: failed to solve: maximum timeout reached
make: *** [Makefile:35: release] Error 1
Error: Process completed with exit code 2.

To mitigate this issue, you can supply a GitHub token to BuildKit. This lets BuildKit utilize the standard GitHub API for checking cache keys, thereby reducing the number of requests made to the cache API.

To provide a GitHub token, you can use the ghtoken parameter, and a repository parameter to specify the repository to use for cache storage. The ghtoken parameter is a GitHub token with the repo scope, which is required to access the GitHub Actions cache API.

The ghtoken parameter is automatically set to the value of secrets.GITHUB_TOKEN when you build with the docker/build-push-action action. You can also set the ghtoken parameter manually using the github-token input, as shown in the following example:

- 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=max
    github-token: ${{ secrets.MY_CUSTOM_TOKEN }}

Further reading

For an introduction to caching see Docker build cache.

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

For more information about using GitHub Actions with Docker, see Introduction to GitHub Actions