Skip to content

docs: correct GitHub Actions cache version selection #26197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sunm2n wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: correct GitHub Actions cache version selection #26197

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions content/manuals/build/cache/backends/gha.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ The following table describes the available CSV parameters that you can pass to

| Name | Option | Type | Default | Description |
|----------------|-------------------------|-------------|------------------------------------------------|----------------------------------------------------------------------|
| `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` or `$ACTIONS_RESULTS_URL` | Cache server URL, see [authentication][1]. Ignored when `version=2`. |
| `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` or `$ACTIONS_RESULTS_URL` | Cache server URL, see [authentication][1] and [version][4]. |
| `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] |
Expand All @@ -42,7 +42,7 @@ The following table describes the available CSV parameters that you can pass to
| `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. |
| `version` | `cache-to`,`cache-from` | String | `1` unless `$ACTIONS_CACHE_SERVICE_V2` is set, then `2` | Selects GitHub Actions cache version, see [version][4] |
| `version` | `cache-to`,`cache-from` | String | Inferred from the cache server URL | Selects GitHub Actions cache version, see [version][4] |

[1]: #authentication
[2]: #scope
Expand Down Expand Up @@ -88,12 +88,23 @@ for affected triggers and how to configure cache imports and exports.

## Version

If you don’t set `version` explicitly, the default is v1. However, if the environment variable `$ACTIONS_CACHE_SERVICE_V2` is set to a value interpreted as `true` ( `1`, `true`, `yes`), then v2 is used automatically.
If you set `version` explicitly, BuildKit uses that version. Otherwise it
selects the version from the cache server URL:

Only one URL is relevant at a time:
- Setting `url_v2` selects v2.
- Otherwise a `url` that points at the v2 cache service
(`results-receiver.actions.githubusercontent.com`) selects v2, and any other
`url` selects v1.

- With v1, use `url` (defaults to `$ACTIONS_CACHE_URL`).
- With v2, use `url_v2` (defaults to `$ACTIONS_RESULTS_URL`).
Inside a workflow, Buildx fills unspecified URL parameters from the
environment. It sets `url_v2` from `$ACTIONS_RESULTS_URL` when you pass
`version=2`, or when you omit `version` and `$ACTIONS_CACHE_SERVICE_V2`
holds a true value such as `1` or `true`. It sets `url` from
`$ACTIONS_CACHE_URL`, falling back to `$ACTIONS_RESULTS_URL` when
`$ACTIONS_CACHE_URL` isn't set.

Only one URL applies to a build. With v2, BuildKit uses `url_v2`, falling back
to `url` when `url_v2` isn't set. With v1, it uses `url`.

### Using `docker/build-push-action`

Expand Down
Loading