Before you start
Docker Buildx, jq, a SHA-256 tool and a KeySigner test release workflow
- Register the package under docker.io with its namespace/repository name. Configure both test release owners and keep access to the exact approved digest. The public rehearsal works without a Docker Hub account.
Data and access
Approve the image index
Use a scratch directory. For the rehearsal, use the public repository and tag below. For your own release, set the repository and tag to your staged image. In the KeySigner test release workflow, use registry docker.io and the registered namespace/repository name. Submit the full index digest, version, source run and commit. Keep the request and digest after both test owners approve.
repository=docker.io/library/hello-world tag=latest docker buildx imagetools inspect "$repository:$tag" \ --format '{{json .Manifest}}' > release-index.json && jq -er .digest release-index.jsonCheck. The request reaches Approved with the full top-level digest returned by Docker Buildx.
Hash what Docker Hub serves
After publication, or immediately for the public rehearsal, resolve the tag again. Fetch the raw index at that digest and hash the file as saved. Formatting the JSON changes the bytes. Compare the hash with the digest Docker Hub returned.
docker buildx imagetools inspect "$repository:$tag" \ --format '{{json .Manifest}}' > observed-index.json && observed=$(jq -er .digest observed-index.json) && docker buildx imagetools inspect --raw "$repository@$observed" \ > observed-index.raw && shasum -a 256 observed-index.rawCheck. The SHA-256 of the raw index matches the full observed digest.
Compare with the approved digest
In KeySigner, use the approved request from Accounts and compare the entire sha256 digest with the observed value. The release requester or an administrator can record the observation with POST /v1/operations/{operation_id}/published-bytes and a JSON body containing the digest field. After the required checks pass, use the digest-qualified reference in deployment.
printf '%s\n' "$repository@$observed"Check. The observed digest matches the approval. If you report it, KeySigner records a matching check.
Try a platform digest
Read the Linux amd64 digest from the saved index. It identifies one platform manifest. Compare it with the approved index digest. If you submit it against the original test request, review the finding in KeySigner. Keep this step in the test workflow.
jq -er '.manifests[] | select(.platform.os == "linux" and .platform.architecture == "amd64") | .digest' observed-index.jsonCheck. The platform digest differs from the approved index. If you report it, KeySigner records Published bytes differ.
Check your result
Use the same index digest in the approval, registry check and deployment reference. Verify any required publisher signature separately for that digest.
What we tested
Tested on . Docker Buildx 0.37.2 resolved the public hello-world index and its Linux amd64 manifest in Docker Hub. The SHA-256 hashes of the raw registry responses matched the two different digests. In a local KeySigner workflow, two owners approved the index digest. KeySigner recorded a match for that digest and a finding for the platform digest.
If you get stuck
Docker Hub returns a different digest
Pause deployment and check whether the tag moved or you compared a platform manifest with the index. If a replacement is intended, request approval for its exact digest and repeat the check.