GitHub Actions cache

Table of contents

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 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 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	`buildkit`	Which scope cache object belongs to, 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.
`timeout`	`cache-to`,`cache-from`	String	`10m`	Max duration for importing or exporting cache before it's timed out.

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, 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.

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@v5
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max

GitHub Actions cache

Synopsis

Authentication

Scope

Using docker/build-push-action

Further reading