Skip to content

docs: correct GitHub Actions cache version selection - #26197

Open
sunm2n wants to merge 1 commit into
docker:mainfrom
sunm2n:docs-gha-cache-version-defaults
Open

sunm2n wants to merge 1 commit into
docker:mainfrom
sunm2n:docs-gha-cache-version-defaults

Conversation

@sunm2n

@sunm2n sunm2n commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

Description

Three claims on the GitHub Actions cache page don't match how Buildx and BuildKit behave.

The version default. The page says the default is 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 (gha.go). Buildx forwards an explicitly supplied version but doesn't add a version attribute based on the environment variable (opt.go#L1522-L1553), so a runner that exposes only $ACTIONS_RESULTS_URL can reach v2 without that variable.

yes as a true value. The page lists yes among the values that enable v2 selection. Buildx parses $ACTIONS_CACHE_SERVICE_V2 with strconv.ParseBool, which rejects yes.

url ignored at v2. The parameter table says url is ignored when version=2. It's ignored only when url_v2 is set; with version=2 and no url_v2, BuildKit falls back to url.

The rewritten Version section also states two conditions the previous text left out: Buildx fills in only unspecified URL parameters, and it checks $ACTIONS_CACHE_SERVICE_V2 only when version is omitted.

Related issues or tickets

None. Found while checking the page against the Buildx and BuildKit sources.

Reviews

  • Technical review
  • Editorial review
  • Product review

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>
@sunm2n
sunm2n requested a review from dvdksn as a code owner September 28, 2026 07:56
@netlify

netlify Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for docsdocker ready!

Name Link
🔨 Latest commit 773efbb
🔍 Latest deploy log https://app.netlify.com/projects/docsdocker/deploys/6aba1dbac97ade0008043eff
😎 Deploy Preview https://deploy-preview-26197--docsdocker.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions Bot added the area/build Relates to Dockerfiles or docker build command label Sep 28, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/build Relates to Dockerfiles or docker build command

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant