13.1.1.3 Pipeline Image Tagging

Pipeline image tagging assigns a meaningful, traceable tag to an image built within a CI/CD pipeline, commonly incorporating the commit SHA, branch name, or build number, providing a clear link between a specific built image and the exact source state it was built from.

Tagging With the Commit SHA for Precise Traceability

Using the triggering commit's SHA as part of the image tag provides an exact, unambiguous link to the source code that produced this specific image.

- run: docker build -t myapp:${{ github.sha }} .

docker pull myapp:a1b2c3d
git show a1b2c3d

Given this tag, the exact corresponding source commit can always be directly identified.

Additionally Tagging With a Branch Name for Convenience

A more human-readable, branch-based tag can be applied alongside the SHA-based one, useful for quickly identifying the latest build from a specific branch.

- run: |
    docker tag myapp:${{ github.sha }} myapp:${{ github.ref_name }}
    docker push myapp:${{ github.sha }}
    docker push myapp:${{ github.ref_name }}

This provides both a precise, immutable reference (the SHA tag) and a convenient, mutable one (the branch tag) pointing to the same actual image content.

Why Moving a Tag Like "latest" Should Happen Deliberately

A pipeline might move a latest (or similar floating) tag only after a build has passed all its checks and is specifically intended to represent the current, deployable state.

- if: github.ref == 'refs/heads/main'
  run: |
    docker tag myapp:${{ github.sha }} myapp:latest
    docker push myapp:latest

This condition ensures latest only moves for builds specifically from the main branch, not for every feature branch's pipeline run.

Why Pipeline Image Tagging Matters

A thoughtful, consistent tagging strategy within a CI/CD pipeline provides essential traceability between deployed images and their exact source origin, while still offering convenient, human-readable references where appropriate.