GitHub Actions Cache for Docker Buildx

--- title: GitHub Actions cache description: Use the GitHub Actions cache to manage your build cache in CI keywords: build, buildx, cache, backend, gha, github, actions aliases: - /build/building/cache/backends/gha/ --- {{< summary-bar feature_name="GitHub Actions cache" >}} The GitHub Actions cache utilizes the [GitHub-provided Action's cache](https://github.com/actions/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](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). 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](/manuals/build/builders/drivers/_index.md) for more information. ## Synopsis ```console $ 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, see [authentication][1]. | | `url_v2` | `cache-to`,`cache-from` | String | `$ACTIONS_RESULTS_URL` | Cache v2 server URL, see [authentication][1]. | | `token` | `cache-to`,`cache-from` | String | `$ACTIONS_RUNTIME_TOKEN` | Access token, see [authentication][1]. | | `scope` | `cache-to`,`cache-from` | String | `buildkit` | Which scope cache object belongs to, see [scope][2] | | `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][3]. | | `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 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`](https://github.com/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

This document describes how to use GitHub Actions cache as a storage backend for Docker Buildx. It explains the parameters available for `--cache-to` and `--cache-from`, such as `url`, `token`, `scope`, and `mode`. It also covers authentication methods using environment variables and the concept of scope for identifying cache objects. The GitHub Actions cache is recommended for use within GitHub Actions workflows, subject to GitHub's usage limits.