nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: correct GitHub Actions cache version selection

Browse Source 
The page said the `gha` cache backend defaults to v1 unless
$ACTIONS_CACHE_SERVICE_V2 is set. When `version` isn't passed, BuildKit
selects v2 if `url_v2` is set, and otherwise infers the version from the
`url` string. Buildx forwards an explicitly supplied version but does not
add a version attribute based on ACTIONS_CACHE_SERVICE_V2, so a runner
that exposes only $ACTIONS_RESULTS_URL can reach v2 without that variable.

It also listed `yes` among the values that enable v2 selection. Buildx
parses the variable with strconv.ParseBool, which rejects `yes`.

The `url` row claimed it is ignored when `version=2`. It is ignored only
when `url_v2` is set; with `version=2` and no `url_v2`, `url` is used.

Signed-off-by: Sunmin Lee <134378502+sunm2n@users.noreply.github.com>
This commit is contained in:
Sunmin Lee committed 2026-09-28 16:48:01 +09:00
1 parent 4e9a575151
commit 773efbb5a2
1 file changed
+17 -6
Download Patch File Download Diff File Expand all files Collapse all files
content/manuals/build/cache/backends/gha.md
Vendored
+17 -6
View File
@@ -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] |
@@ -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
@@ -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`