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

This cache storage backend is not supported with the defaultdocker driver.To use this feature, create a new builder using a different driver. SeeBuild 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 theurl,url_v2 ortoken parameters are left unspecified, theghacache backend will fall back to using environment variables. If you invoke thedocker buildx command manually from an inline step, then the variables mustbe manually exposed. Consider using thecrazy-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 tobuildkit. If you build multiple images, each build will overwrite the cacheof the previous, leaving only the final cache.

To preserve the cache for multiple builds, you can specify this scope attributewith a specific name. In the following example, the cache is set to the imagename, 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'scache access restrictions,still apply. Only the cache for the current branch, the base branch and thedefault branch is accessible by a workflow.

Usingdocker/build-push-action

When using thedocker/build-push-action, theurl andtoken parameters are automatically populated. No need to manuallyspecify them, or include any additional workarounds.

For example:

-name:Build and pushuses:docker/build-push-action@v6with:context:.push:truetags:"<registry>/<image>:latest"cache-from:type=ghacache-to:type=gha,mode=max

Avoid GitHub Actions cache API throttling

GitHub'susage limits and eviction policycauses stale cache entries to be removed after a certain period of time. Bydefault, thegha cache backend uses the GitHub Actions cache API to check thestatus of cache entries.

The GitHub Actions cache API is subject to rate limiting if you make too manyrequests in a short period of time, which may happen as a result of cachelookups during a build using thegha 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 reachedmake: *** [Makefile:35: release] Error 1Error: Process completed with exit code 2.

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

To provide a GitHub token, you can use theghtoken parameter, and arepository parameter to specify the repository to use for cache storage. Theghtoken parameter is a GitHub token with therepo scope, which is requiredto access the GitHub Actions cache API.

Theghtoken parameter is automatically set to the value ofsecrets.GITHUB_TOKEN when you build with thedocker/build-push-actionaction. You can also set theghtoken parameter manually using thegithub-token input, as shown in the following example:

-name:Build and pushuses:docker/build-push-action@v6with:context:.push:truetags:"<registry>/<image>:latest"cache-from:type=ghacache-to:type=gha,mode=maxgithub-token:${{ secrets.MY_CUSTOM_TOKEN }}

Further reading

For an introduction to caching seeDocker build cache.

For more information on thegha cache backend, see theBuildKit README.

For more information about using GitHub Actions with Docker, seeIntroduction to GitHub Actions