build/bake: preserve tag refs in git contexts

[crazy-max]

This change preserves Git tag names when the reusable workflows build from a tag event by passing the event SHA as the Git context checksum. Non-tag refs continue to use fetch-by-commit, so the existing branch and pull request behavior is unchanged.

Projects like Buildx and BuildKit derive their version metadata from the Git ref that BuildKit checks out. When the Git context only uses the commit SHA, the built binary reports the short SHA as the version instead of the tag name.

The failing case was reproduced with https://github.com/docker/buildx/actions/runs/27313485396/job/80688869371#step:11:476:

/usr/bin/docker buildx bake https://github.com/docker/buildx.git?ref=89b455a9e38ca3808e94190ce5c54193c9cb2e06 --allow fs=* --file docker-bake.hcl --set *.output=type=local,platform-split=true,dest=/tmp/buildx-output --set *.tags= --set *.attest=type=provenance,mode=max,version=v1,builder-id=https://github.com/docker/buildx/actions/runs/27313485396/attempts/1 --set *.platform=darwin/amd64 --set *.cache-from=type=gha,scope=bin-image-darwin-amd64 --set *.cache-to=type=gha,ignore-error=true,scope=bin-image-darwin-amd64,mode=min --metadata-file /home/runner/work/_temp/docker-actions-toolkit-f39NML/bake-metadata-569c3515e6.json --sbom generator=docker/buildkit-syft-scanner:1.11.0 release
...

#24 [buildx-build 1/1] RUN --mount=type=bind,target=.   --mount=type=cache,target=/root/.cache   --mount=type=cache,target=/go/pkg/mod   --mount=type=bind,from=buildx-version,source=/tmp/.ldflags,target=/tmp/.ldflags <<EOT (set -ex...)
#24 0.057 + cat /tmp/.ldflags
#24 0.057 + xx-go build -trimpath -ldflags '-s -w -X github.com/docker/buildx/version.Version=89b455a -X github.com/docker/buildx/version.Revision=89b455a9e38ca3808e94190ce5c54193c9cb2e06 -X github.com/docker/buildx/version.Package=github.com/docker/buildx' -o /usr/bin/docker-buildx ./cmd/buildx
#24 66.93 + file /usr/bin/docker-buildx
...

That build produced ldflags with github.com/docker/buildx/version.Version=89b455a, so the binary version was based only on the commit SHA.

The working query case was reproduced with:

$ docker buildx bake --no-cache "https://github.com/docker/buildx.git?ref=refs/tags/v0.35.0-rc1&checksum=89b455a9e38ca3808e94190ce5c54193c9cb2e06"
...
#13 [buildx-build 1/1] RUN --mount=type=bind,target=.   --mount=type=cache,target=/root/.cache   --mount=type=cache,target=/go/pkg/mod   --mount=type=bind,from=buildx-version,source=/tmp/.ldflags,target=/tmp/.ldflags <<EOT (set -ex...)
#13 0.424 + cat /tmp/.ldflags
#13 0.424 + xx-go build -trimpath -ldflags '-s -w -X github.com/docker/buildx/version.Version=v0.35.0-rc1 -X github.com/docker/buildx/version.Revision=89b455a9e38ca3808e94190ce5c54193c9cb2e06 -X github.com/docker/buildx/version.Package=github.com/docker/buildx' -o /usr/bin/docker-buildx ./cmd/buildx
#13 20.87 + file /usr/bin/docker-buildx

That keeps the tag ref available for version metadata while still validating that the tag resolves to the expected commit.

You can add this after the paragraph that says projects derive version metadata from the Git ref:

The important detail is that the Git context ref is not only a pin. It's also the ref name that BuildKit resolves and checks out for the source. In the failing workflow invocation, ref=89b455a9e38ca3808e94190ce5c54193c9cb2e06 tells BuildKit to resolve the source directly by commit SHA. The checkout is therefore identified by that commit, not by refs/tags/v0.35.0-rc1, so the Buildx version generation cannot recover the release tag from the ref that selected the source.

Using ref=refs/tags/v0.35.0-rc1&checksum=89b455a9e38ca3808e94190ce5c54193c9cb2e06 separates the human version identity from the immutable commit validation. The ref remains the tag ref, so BuildKit resolves the source through the tag and the Buildx version metadata sees v0.35.0-rc1. The checksum then asserts that this tag must resolve to the expected event commit. If the tag points anywhere else, Git context resolution fails before the build starts. This preserves the tag version in the binary while still pinning the source to the exact commit that triggered the workflow.