GitHub Actions cache
Experimental
This is an experimental feature. The interface and behavior are unstable and may change in future releases.
The GitHub Actions cache utilizes the GitHub-provided Action's cacheopen_in_new available from within 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 GitHubopen_in_new.
This cache storage backend is not supported with the default docker
driver.
To use this feature, create a new builder using 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
.
Name | Option | Type | Default | Description |
---|---|---|---|---|
url | cache-to ,cache-from | String | $ACTIONS_CACHE_URL | Cache server URL, see authentication. |
token | cache-to ,cache-from | String | $ACTIONS_RUNTIME_TOKEN | Access token, see authentication. |
scope | cache-to ,cache-from | String | Name of the current Git branch. | Cache scope, see scope |
mode | cache-to | min ,max | min | Cache layers to export, see cache mode. |
ignore-error | cache-to | Boolean | false | Ignore errors caused by failed cache exports. |
Authentication
If the url
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
open_in_new,
GitHub Action as a helper for exposing the variables.
Scope
By default, cache is scoped per Git branch. This ensures a separate cache environment for the main branch and each feature branch. If you build multiple images on the same branch, each build will overwrite the cache of the previous, leaving only the final cache.
To preserve the cache for multiple builds on the same branch, you can manually
specify a cache scope name using the scope
parameter. In the following
example, the cache is set to a combination of the branch name and 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=$GITHUB_REF_NAME-image \
--cache-from type=gha,url=...,token=...,scope=$GITHUB_REF_NAME-image .
$ docker buildx build --push -t <registry>/<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 access restrictionsopen_in_new, still apply. Only the cache for the current branch, the base branch and the default branch is accessible by a workflow.
Using docker/build-push-action
When using the
docker/build-push-action
open_in_new, 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@v5
with:
context: .
push: true
tags: "<registry>/<image>:latest"
cache-from: type=gha
cache-to: type=gha,mode=max
Further reading
For an introduction to caching see Optimizing builds with cache.
For more information on the gha
cache backend, see the
BuildKit READMEopen_in_new.
For more information about using GitHub Actions with Docker, see Introduction to GitHub Actions