mirror of
https://gitea.com/Lydanne/buildx.git
synced 2025-05-22 19:57:44 +08:00
04b56c7331
This fleshes out the documentation to include information along with examples and detailed use cases for the cache backends. The general format and style follows from the style of the build driver docs. Eventually, these docs will be included on docs.docker.com along with the rest of the build docs. Signed-off-by: Justin Chadwell <me@jedevc.com>
110 lines
4.6 KiB
Markdown
110 lines
4.6 KiB
Markdown
# GitHub Actions cache storage
|
|
|
|
> **Warning**
|
|
>
|
|
> The `gha` cache is currently experimental. You can use it today, in current
|
|
> releases of Buildx and Buildkit, however, the interface and behavior do not
|
|
> have any stability guarantees and may change in future releases.
|
|
|
|
The `gha` cache utilizes the [GitHub-provided Action's cache](https://github.com/actions/cache)
|
|
available from inside 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 GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy).
|
|
|
|
> **Note**
|
|
>
|
|
> The `gha` cache storage backend requires using a different driver than
|
|
> the default `docker` driver - see more information on selecting a driver
|
|
> [here](../drivers/index.md). To create a new docker-container driver (which
|
|
> can act as a simple drop-in replacement):
|
|
>
|
|
> ```console
|
|
> docker buildx create --use --driver=docker-container
|
|
> ```
|
|
>
|
|
> If you're using the official [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action),
|
|
> then this step will be automatically run for you.
|
|
|
|
To import and export your cache using the `gha` storage backend we use the
|
|
`--cache-to` and `--cache-from` flags configured with the appropriate
|
|
[Authentication](#authentication) parameters:
|
|
|
|
```console
|
|
$ docker buildx build --push -t <user>/<image> \
|
|
--cache-to type=gha,url=...,token=...
|
|
--cache-from type=gha,url=...,token=...
|
|
```
|
|
|
|
By default, caches are scoped by branch - this ensures a separate cache
|
|
environment for the main branch, as well as for each feature branch. However,
|
|
if you build multiple images as part of your build, then caching them both to
|
|
the same `gha` scope will overwrite all but the last build, leaving only the
|
|
final cache.
|
|
|
|
To prevent this, you can manually specify a cache scope name using the `scope`
|
|
parameter (in this case, including the branch name set [by GitHub](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables)
|
|
to ensure each branch gets its own cache):
|
|
|
|
```console
|
|
$ docker buildx build --push -t <user>/<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 <user>/<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 scoping rules](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache),
|
|
still apply, with the cache only populated from the current branch, the base
|
|
branch and the default branch for a run.
|
|
|
|
## Authentication
|
|
|
|
To authenticate against the [GitHub Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication)
|
|
to read from and write to the cache, the following parameters are required:
|
|
|
|
* `url`: cache server URL (default `$ACTIONS_CACHE_URL`)
|
|
* `token`: access token (default `$ACTIONS_RUNTIME_TOKEN`)
|
|
|
|
If the parameters are not specified, then their values will be pulled from the
|
|
environment variables. If invoking the `docker buildx` command manually from an
|
|
inline step, then the variables must be manually exposed, for example, by using
|
|
[crazy-max/ghaction-github-runtime](https://github.com/crazy-max/ghaction-github-runtime)
|
|
as a workaround.
|
|
|
|
### With [docker/build-push-action](https://github.com/docker/build-push-action)
|
|
|
|
When using the [docker/build-push-action](https://github.com/docker/build-push-action),
|
|
the `url` and `token` parameters are automatically populated, with no need to
|
|
manually specify them, or include any additional workarounds.
|
|
|
|
For example:
|
|
|
|
```yaml
|
|
-
|
|
name: Build and push
|
|
uses: docker/build-push-action@v3
|
|
with:
|
|
context: .
|
|
push: true
|
|
tags: user/app:latest
|
|
cache-from: type=gha
|
|
cache-to: type=gha,mode=max
|
|
```
|
|
|
|
<!-- FIXME: cross-link to ci docs once docs.docker.com has them -->
|
|
|
|
## Cache options
|
|
|
|
The `gha` cache has lots of parameters to adjust its behavior.
|
|
|
|
### Cache mode
|
|
|
|
See [Registry - Cache mode](./registry.md#cache-mode) for more information.
|
|
|
|
## Further reading
|
|
|
|
For an introduction to caching see [Optimizing builds with cache management](https://docs.docker.com/build/building/cache).
|
|
|
|
For more information on the `gha` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental).
|