Skip to content

Tagging Docker Images for Fun and Profit

Last updated on May 5, 2020

We ❤️ Docker. It’s enabled us to have more confidence that our dev environments match production and has made deployments a breeze. Something that I’ve struggled with is effectively naming the images I generate. I’ve struggled to find consensus online about how this should be done, so have come up with something that I’ve not really seen around.

First, the problem: in some environments there’s a sensibly versioned artifact that’s pretty easy to name. For instance, packaging up an OS or a major release of publicly distributed software. In these scenarios, we’re burdened with versioning anyway so figuring out a slick system isn’t as important.

We don’t release binaries for sale, and generally operate software as a service. I don’t really want to have to enforce manual versioning through code review and the tech stack we’re using doesn’t have a slick way to verify that our versioning is correct. Most automated versioning I’ve seen just increments the PATCH version even if a contract is completely violated.

That’s why we decided to start versioning artifacts with the first eight chars from the git commit SHA. This worked great! If we see a bug in prod, we can quickly figure out what version is currently running and check it out locally. Unfortunately, it doesn’t give a quick view into order when looking at a docker registry. That’s why we’ve made an addition to this format – the date.

We now name our continuously deployed docker images (built then deployed to staging/prod in a single pipeline) like so $IMAGE_NAME:YYYY-MM-DD-$SHA. While this doesn’t give us great granularity in terms of order of changes within a single day, we’ve found it to be a happy medium. I guess an alternative on a larger team might be to use an incrementing count, but that’s harder to manage than ‘what day is today?’

We like to build our docker images early in our pipeline to use in the integration tests (a topic for a later post), so this make it pretty easy for subsequent pipeline stages to figure out what image it should run for the next test, without having to carry over artifacts from the previous stage in a stateful way.

That’s it for now, I’ll write more on this topic again I’m sure.

Published inTechnical


  1. Ian Morris Nieves Ian Morris Nieves

    This was actually super relevant to me, thanks for sharing!

  2. Riley Riley

    We had a similar issues the 8 char sha. We ended up using this:
    `git rev-list –count HEAD` in addition to the 8 char sha.

    This gives us ordering and ability to lookup version.

    • Neat! On the Hacker News discussion a bunch of people suggested various ways of achieving this – CI build number etc – but I like this one the best.

Leave a Reply

Your email address will not be published. Required fields are marked *

Creative Commons License
Except where otherwise noted, Happy Valley IO Blog by Happy Valley IO is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
You are welcome to buy a license for any post on this site by contacting