GitHub Actions cache
Page options
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
.
Name | Option | Type | Default | Description |
---|---|---|---|---|
url | cache-to ,cache-from | String | $ACTIONS_CACHE_URL or$ACTIONS_RESULTS_URL | Cache server URL, seeauthentication. |
url_v2 | cache-to ,cache-from | String | $ACTIONS_RESULTS_URL | Cache v2 server URL, seeauthentication. |
token | cache-to ,cache-from | String | $ACTIONS_RUNTIME_TOKEN | Access token, seeauthentication. |
scope | cache-to ,cache-from | String | buildkit | Which scope cache object belongs to, seescope |
mode | cache-to | min ,max | min | Cache layers to export, seecache mode. |
ignore-error | cache-to | Boolean | false | Ignore errors caused by failed cache exports. |
timeout | cache-to ,cache-from | String | 10m | Max duration for importing or exporting cache before it's timed out. |
repository | cache-to | String | GitHub repository used for cache storage. | |
ghtoken | cache-to | String | GitHub token required for accessing the GitHub API. |
Authentication
If theurl
,url_v2
ortoken
parameters are left unspecified, thegha
cache 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-action
action. 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