# Check an approved Docker Hub image digest

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/check-an-approved-docker-hub-image/)

Check that Docker Hub serves the exact multi-platform image your KeySigner release owners approved. Practice with the public hello-world image without publishing or changing a tag.

## 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

- **Shared or checked**. Docker Buildx reads public image metadata and raw index bytes from Docker Hub. KeySigner records the release request and any digest the requester or an administrator reports.
- **Check separately**. Verify the publisher separately and use the approved digest in your deployment. For private images, use your own authorized registry access.

## 1. 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.json
~~~

**Check.** The request reaches Approved with the full top-level digest returned by Docker Buildx.

## 2. 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.raw
~~~

**Check.** The SHA-256 of the raw index matches the full observed digest.

## 3. 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.

## 4. 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.json
~~~

**Check.** 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 November 19, 2026.** 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.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## 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.

## Tools in this guide

- [Docker Hub](https://keysigner.io/integrations/docker-hub/)
  - [Review publishing token permissions](https://docs.docker.com/security/access-tokens/personal-access-tokens/)
  - [Enable two-factor authentication in Docker](https://docs.docker.com/security/authentication/2fa/manage/#enable-two-factor-authentication)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#docker-hub)

## Setup instructions

- [Review the KeySigner release workflow](https://keysigner.io/integrations/guides/troubleshoot-a-package-release-approval/)
- [Inspect an image with Docker Buildx](https://docs.docker.com/reference/cli/docker/buildx/imagetools/inspect/)
- [Pull by digest with Docker](https://docs.docker.com/reference/cli/docker/image/pull/)
- [Practice with the Docker Official hello-world image](https://hub.docker.com/_/hello-world)
- [Check the image publisher with Notation](https://keysigner.io/integrations/guides/check-an-approved-image-with-notation/)
- [Review release history and digest findings](https://keysigner.io/integrations/approval-history/#release)

[More guides for this task](https://keysigner.io/integrations/tasks/review-code-and-releases/)
