docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-07-19 09:48:03 +08:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: additions from editorial review

Browse Source 
- editorial review
- address review comments, rework param sections
- added a common section for parameters
- remove liquid tags for notes

Signed-off-by: David Karlsson <david.karlsson@docker.com>
Signed-off-by: Justin Chadwell <me@jedevc.com>
This commit is contained in:
David Karlsson
2022-09-21 15:38:03 +02:00
committed by Justin Chadwell
parent 04b56c7331
commit 91f0ed3fc3
7 changed files with 418 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/guides/cache/gha.md vendored
View File

@@ -2,108 +2,109 @@
> **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 GitHub Actions cache is a beta feature. You can use it today, in current
> releases of Buildx and BuildKit. However, the interface and behavior are
> unstable 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).
The GitHub Actions cache utilizes the
[GitHub-provided Action's cache](https://github.com/actions/cache) 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 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):
> This 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 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:
## Synopsis
```console
$ docker buildx build --push -t <user>/<image> \
--cache-to type=gha,url=...,token=...
--cache-from type=gha,url=...,token=...
$ docker buildx build . --push -t <registry>/<image> \
--cache-to type=gha[,parameters...] \
--cache-from type=gha[,parameters...]
```
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.
Common parameters:
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):
- `url`: cache server URL (default `$ACTIONS_CACHE_URL`), see
[authentication](#authentication)
- `token`: access token (default `$ACTIONS_RUNTIME_TOKEN`), see
[authentication](#authentication)
- `scope`: cache scope (defaults to the name of the current Git branch).
Parameters for `--cache-to`:
- `mode`: specify cache layers to export (default: `min`), see
[cache mode](./index.md#cache-mode)
## 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 (using
[`crazy-max/ghaction-github-runtime`](https://github.com/crazy-max/ghaction-github-runtime),
for example).
## 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 branch gets its own cache):
```console
$ docker buildx build --push -t <user>/<image> \
$ 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 <user>/<image2> \
$ 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 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.
GitHub's
[cache access restrictions](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache),
still apply. Only the cache for the current branch, the base branch and the
default branch is accessible by a workflow.
## Authentication
### Using `docker/build-push-action`
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.
When using the
[`docker/build-push-action`](https://github.com/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:
```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
- name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: "<registry>/<image>: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 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).
For more information on the `gha` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental).