阅读中文版本

Version Container Images with the Git SHA

Tag images with immutable commit SHAs and digest digests so deployments reference an exact artifact rather than a moving tag.

docker buildx build --push \
  -t ghcr.io/org/app:${GITHUB_SHA} \
  -t ghcr.io/org/app:latest .
docker buildx imagetools inspect ghcr.io/org/app:${GITHUB_SHA} | grep Digest

image: ghcr.io/org/app:${GITHUB_SHA}

What this recipe does

Tag and deploy images by immutable git SHA and record the image digest for audit.

A deploy uses the latest tag, and two environments end up running different code from the same tag.

Prerequisites

• A container registry
• CI with the commit SHA available
• A deploy manifest referencing the image

Procedure

1. Build and push with a SHA tag plus the digest.

docker buildx build --push \
  -t ghcr.io/org/app:${GITHUB_SHA} \
  -t ghcr.io/org/app:latest .
docker buildx imagetools inspect ghcr.io/org/app:${GITHUB_SHA} | grep Digest

Expected result: The SHA tag is unique per commit and the digest pins the bytes.

2. Reference the SHA tag in the deployment.

image: ghcr.io/org/app:${GITHUB_SHA}

Expected result: The deployed workload runs the exact commit that passed tests.

How to confirm it worked

Run the commands above and confirm every expected result in order. If a step does not produce the stated output, use the troubleshooting notes before continuing. A passing run shows the running image digest matches the registry digest for the commit, and a redeploy is byte-identical.

Troubleshooting

Rollback references a tag that was overwritten — Deploy by digest or never reuse a mutable tag.

Registry retains too many tags — Add a retention policy keyed on age and keep release tags.

Limitations

• Requires immutable tags or digest references.
• Does not by itself verify provenance.
• Short SHAs can collide in theory; use full SHAs.