CI/CD Image Tagging and Versioning

The Problem with latest and The Power of Immutable Tags

The core issue with the :latest tag is that it's mutable—it can point to different images over time. If you deploy myapp:latest today, it might be a completely different image from the one deployed yesterday, even though the tag is the same. This violates the principle of immutability and creates several problems:

• Traceability: You can't easily determine which specific Git commit is running in production.
• Reproducibility: You can't reliably pull the exact same image that caused an issue for debugging.
• Rollbacks: You can't roll back to a previous "latest" version because that tag has been overwritten.

To solve this, we use immutable tags. These are tags that, once created, should never be overwritten. They point to one specific version of your image forever.

The following resource clearly distinguishes between good and bad tagging practices.

As the article shows, good immutable tags often include:

• Semantic Versioning: 1.2.3
• Git Commit SHA: sha-abc1234
• Branch or Pull Request Identifier: pr-123

Let's explore these strategies, starting with the most common one for production releases: Semantic Versioning.

Understanding Semantic Versioning (SemVer)

Semantic Versioning (SemVer) is a widely adopted standard that communicates the nature of changes in a release through a MAJOR.MINOR.PATCH versioning scheme.

• MAJOR version is incremented for incompatible API changes (breaking changes).
• MINOR version is incremented when you add functionality in a backward-compatible manner.
• PATCH version is incremented when you make backward-compatible bug fixes.

In a CI/CD context, the act of creating a Git tag (e.g., git tag -a v1.2.3 -m "Release version 1.2.3") is often the trigger that signals a new release. The CI pipeline then uses this Git tag to version the corresponding Docker image.

A Strategy for Automated Tagging

A robust CI/CD pipeline should automatically apply different tags based on the event that triggered it. This gives every image a meaningful, traceable context. Here's a common strategy:

The following diagram illustrates how version tags fit into a typical Git branching model, marking specific commits on the main branch as formal releases.

This table from the DeployU article provides a great summary.

Implementing Automated Tagging in GitHub Actions

Now for the practical part. How do we implement this in our GitHub Actions workflow? Manually constructing these tags would be complex and error-prone. Fortunately, the Docker ecosystem provides a powerful tool for this: the docker/metadata-action.

This action inspects the GitHub event that triggered the workflow (e.g., a push, a tag) and automatically generates a set of appropriate tags and labels for your image.

Let's integrate this into the docker-publish.yml workflow we've been building.

1. Add a meta step using docker/metadata-action before the build-and-push step.
2. Configure the tags to generate tags for branches, pull requests, semantic versions from Git tags, and the commit SHA.
3. Update the build-and-push step to use the output of the meta step (${{ steps.meta.outputs.tags }}) instead of a hardcoded tag.

Here is the updated build-and-push job from our workflow:

  build-and-push:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # This new step generates tags and labels automatically
      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: your-dockerhub-username/my-app # Replace with your image name
          tags: |
            # tag with git branch name for branch pushes
            type=ref,event=branch
            # tag with PR number for PR events
            type=ref,event=pr
            # tag with commit SHA
            type=sha
            # tag with semantic version for git tags
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push with cache and tags
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          # Use the tags generated in the 'meta' step
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/amd64,linux/arm64
          cache-from: type=registry,ref=your-dockerhub-username/my-app:buildcache
          cache-to: type=registry,ref=your-dockerhub-username/my-app:buildcache,mode=max

With this configuration:

• A push to the main branch will create an image tagged with main and sha-abcdef.
• Creating a Git tag v2.1.0 and pushing it will create images tagged 2.1.0 and 2.1.

Conclusion

Congratulations! You have now replaced the fragile latest tag with a robust, automated versioning strategy. This is a critical step in professionalizing your CI/CD pipeline.

Key Takeaways:

• Embrace Immutability: Avoid the mutable :latest tag in favor of immutable tags like SemVer (1.2.3), Git SHAs (sha-abcde), and branch names to ensure traceability and enable reliable rollbacks.
• Map Triggers to Tags: Define a clear strategy that maps CI/CD events (push to main, create Git tag, open PR) to specific, meaningful tag patterns.
• Automate with docker/metadata-action: Use this powerful GitHub Action to automatically generate tags based on the workflow trigger, eliminating manual effort and errors.
• Integrate into the Pipeline: Pipe the output of the metadata action directly into your docker/build-push-action to tag and push your image in one seamless flow.

In our next lesson, we will focus on automating the push of images to a container registry as a distinct part of a deployment pipeline. We'll discuss conditional pushing—for example, only pushing release-tagged images to a production registry—and how this automated push can trigger subsequent deployment steps.