Tag release images with an immutable version plus the commit SHA, and deploy by digest. OCI tags may be at most 128 characters and must match a fixed pattern of letters, digits, underscore, period and hyphen. Treat moving tags such as latest as convenience labels, never as the thing production runs.
What the specification allows
The OCI distribution specification says a tag must be at most 128 characters and match this regular expression:
[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}
So a tag cannot start with a period or hyphen, and cannot contain a plus sign or slash. That affects semantic version build metadata: 1.4.0+abc123 is not a legal tag, so many teams write 1.4.0-abc123 or use a separate tag.
A scheme that works
| Tag | Example | Moves? | Use |
|---|---|---|---|
| Full version | 1.4.0 | Never | The release name |
| Version and commit | 1.4.0-3f9c2ab | Never | Trace back to source |
| Minor line | 1.4 | Yes | Convenience for humans |
| Digest | sha256:... | Never | What deployment references |
Only the first two should be trusted. Moving tags are fine for developers, but production manifests should carry the digest.
Steps
- Build once per commit and tag with the commit SHA.
- On release, add the version tag to the same digest. Do not rebuild.
- Record the digest in the release notes and in your change record.
- Turn on tag immutability where the registry supports it. See how to make ECR tags immutable.
- Reference the digest in deployment manifests, and let a policy reject tag only references. See require image digests with an admission policy.
Why not rebuild per environment
A rebuild produces a new digest, so what you tested is not what you shipped. Promote the same artifact instead: build once, promote the same artifact.
Verify after you push
After a release push, pull the image by its tag on a clean machine and compare the digest to the one in your release record. If they differ, something moved, and you want to know before a customer does. Do the same check after promotion between registries, because a copy that changed the manifest changes the digest and breaks any signature tied to the original.
Tags are also a communication tool. A short, consistent scheme lets support and security staff say exactly which build a customer runs, and lets an advisory reference an unambiguous version. Write the scheme down in the release runbook so it survives staff changes.
Naming mistakes to avoid
- Reusing a version tag after a fix. Publish a new patch version.
- Encoding secrets, branch names with slashes or customer names in tags.
- Using only latest. Nobody can say what that was last Tuesday.
- Letting every developer push release tags. Restrict who can.
Safeguard's policy gates can evaluate the image behind a tag at pull request and release time, so the check follows the digest.
Quick check
Can a Docker tag contain a plus sign?
No. The permitted characters are letters, digits, underscore, period and hyphen, and the tag cannot start with a period or hyphen.
Should production deploy by tag or digest?
By digest. A tag can be moved unless the registry forbids it, while a digest names exact content.
Sources
Last reviewed: 19 October 2026.
