A digest identifies fixed content, while a tag is a human readable pointer to a manifest. The OCI distribution spec lets clients pull by either, requires clients to verify a digest pull, and does not forbid repointing a tag. For repeatable deploys, pull by digest.
Pulling
The spec's manifest endpoint accepts a tag or a digest. A tag must be at most 128 characters and match the pattern [a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}. A found manifest returns 200, a missing one 404. The response carries a Docker-Content-Digest header.
The spec says that if the request used a digest, clients should verify that the returned manifest matches. It also says the manifest must be stored in the exact bytes the client provided, so a digest identifies fixed content. For a tag pull the spec defines no verification requirement, and the digest returned can differ from one returned earlier.
Are tags mutable?
The spec does not state it outright, and it does not forbid repointing. It describes a tag as a custom, human readable pointer to a manifest, says a manifest may have zero, one or many tags, and allows a manifest to be pushed to a tag reference. Its referrers section warns that several clients updating the same tag at once can race, which implies tags change in place.
So app:1.4 can mean different content next week unless your registry or policy blocks overwrites. Check whether your registry software offers immutable tags, since the base spec does not require it.
Deleting
| Action | Endpoint | Success | If disabled |
|---|---|---|---|
| Delete a tag | DELETE /v2/<name>/manifests/<tag> | 202 Accepted | 400 or 405 |
| Delete a manifest | DELETE /v2/<name>/manifests/<digest> | 202 Accepted | 400 or 405 |
Tag deletion is optional. A registry may allow deletion only by manifest. After deleting a manifest, a GET by digest returns 404, and so does any tag that pointed to it. The spec does not say whether the tags are removed or merely return 404.
This has a security angle. Deleting a manifest affects every tag that pointed at it, so a cleanup job that removes by digest can break tags you did not intend to touch.
What to do
- Deploy by digest. Record the digest in manifests or lockfiles, so a moved tag cannot change what runs.
- Treat tags as labels for humans, not as promises.
- Turn on immutable tags if your registry supports it, at least for release tags.
- Limit who can push to release tags and who can delete.
- Verify digests in your pull tooling and fail on mismatch.
- Store the digest in your SBOM and release records, so incident response can name the exact image.
Try it yourself
Click through it at your own pace, or open it full screen.
Run the scan and notice that a result belongs to one image. A digest is how you tie a finding to exactly that image.
Safeguard can scan container images and generate SBOMs per image, with a free scan at gold.safeguard.sh/scan.
Quick check
Can the same tag point to different images over time?
Yes, the spec does not forbid it. Pull by digest when you need the same content every time.
What happens to tags when I delete a manifest by digest?
The spec says tags that pointed to that digest return 404 afterwards. It does not say whether they are removed.
Sources
Last reviewed: 19 October 2026.
