Context
An image tag is a convenient name that can move to different content. A digest identifies content, but a multi-platform release introduces another distinction: the digest can identify an image index containing platform choices, or a manifest for one platform. Pinning a digest without understanding that level can make a release reproducible on one machine and unusable on another.
Prerequisites are the approved registry reference, expected release, target operating systems and architectures, and registry read access. The initial commands inspect metadata. They do not push an image, change a tag, or update a running workload.
1. Inspect the registry object
docker buildx imagetools inspect registry.example.test/team/catalog:release
The registry and tag are illustrative. Read the media type, top-level digest, and listed platform manifests. Record the selected platform explicitly. Do not treat a familiar tag name as proof that the tested artifact is still behind that tag; compare the registry digest captured by the build and release workflow.
For an image with attestations or auxiliary manifests, distinguish those entries from runnable platform manifests. An unfamiliar entry is not automatically evidence of a broken build. Read the media type and platform fields before deciding which object the deployment needs.
2. Choose the pinning boundary
A multi-platform index digest preserves the approved set of platform choices. A platform-manifest digest identifies one particular platform image. Your release process should state which it publishes and which it deploys.
For an explicitly illustrative example, developers test linux/arm64 while production runs linux/amd64. The release index contains both variants, but a copied arm64 manifest digest refers only to that variant. Before promotion, verify that the production platform is present in the approved index or choose the intended production manifest according to the deployment contract.
Avoid inventing a digest in configuration. Copy the complete value from trusted registry or build metadata, and preserve its association with the repository, build source, and target platform.
3. Compare registry identity with runtime evidence
Inspect the local image and container metadata without changing them:
docker image inspect registry.example.test/team/catalog:release
docker container inspect catalog
Check architecture and operating-system information, the container's configured reference, and its image identity. Repository digests, image IDs, index digests, and manifest digests describe related but different objects. A local image configuration ID should not be expected to equal the registry's index digest.
Diagnose a release-identity mismatch
| Observation | Likely explanation | Next evidence |
|---|---|---|
| Same tag now resolves to another digest | Mutable tag changed | Registry history and recorded build metadata |
| Pinned artifact lacks target architecture | Wrong manifest or incomplete index | Platform list and release target |
| Local image ID differs from registry digest | Different identity layers | Media type and manifest/config relationship |
| Correct image starts but application fails | Runtime compatibility | Application behavior and native dependencies |
Digest pinning does not automatically refresh vulnerable dependencies. It makes change explicit. Maintain a reviewed update process that builds or selects a new artifact, validates it, and changes the pin deliberately.
Verify promotion and maintain an artifact register
In a controlled test environment, pull or run the approved digest for every supported platform and exercise a harmless application check. Verify the resulting runtime platform and release version. Confirm a subsequent registry lookup still identifies the same content.
Record repository, tag used for discovery, index or manifest digest, platform, source revision, and acceptance evidence in the release SOP. Monitor deployments for references outside that register. Revalidate native dependencies when adding a new architecture, even when the same source code builds successfully.
Explore Clouvenix docker consulting for implementation and operational handover.
Technical reference
Image digest concepts, registry inspection and multi-platform builds.