How to tag and version Docker images?

· Category: Docker

Short answer

Tag Docker images using docker tag with meaningful identifiers like semantic versions, Git commit SHAs, and build numbers. Push multiple tags to registries for flexibility and traceability.

Steps

  1. Build the image.
  2. Tag with the version: docker tag myapp myrepo/myapp:v1.2.3.
  3. Tag with the Git SHA: docker tag myapp myrepo/myapp:sha-abc123.
  4. Push all tags to the registry.

Example

VERSION=1.2.3
SHA=$(git rev-parse --short HEAD)

 docker build -t myapp .
 docker tag myapp myrepo/myapp:${VERSION}
 docker tag myapp myrepo/myapp:sha-${SHA}
 docker tag myapp myrepo/myapp:latest

 docker push myrepo/myapp:${VERSION}
 docker push myrepo/myapp:sha-${SHA}
 docker push myrepo/myapp:latest

Tips

  • Avoid relying solely on latest in production.
  • Use CI pipeline variables to automate tagging.
  • Immutable tags prevent accidental overwrites.

Common issues

  • Overwriting latest without a version tag makes rollbacks difficult.
  • Long tag names may hit registry length limits.
  • Pushing multiple tags for the same image is efficient because layers are shared.