Use Docker tags to document the lifecycle of an image

A Docker image typically goes through a lifecycle:

  1. built: the image is successfully built
  2. tested: the image has successfully passed tests (e.g. integration tests, security tests)
  3. deployed to staging: the image is deployed into the staging environment
  4. deployed to production: the image is deployed into the production environment

It’s advantageous to add a new tag when the image progresses to a new stage in the lifecycle.

As an example, take the Git commit SHA 0b3da7f:

  1. If an image is built from this Git commit, the Docker image can be tagged as built-0b3da7f.
  2. Once tests have passed, it can be tagged additionally as tested-0b3da7f (note that previously added tags are kept).
  3. Once deployed to staging, it can be tagged as deployed-staging-0b3da7f.
  4. Once deployed to production, it can be tagged as deployed-production-0b3da7f.

Advantages to cleanup

The list of tags can be used to be clean up stale Docker images. For each Docker image, the following can be checked:

Advantages to safety

When deploying a Git commit, the deploy script can construct the appropriate Docker tag to deploy. For example, to perform a staging deploy, concatenate tested- with the (short) Git SHA, e.g. tested-0b3da7f. Pull the Docker image with that tag and deploy it.

The deployment will fail if no Docker image with such a tag exists. In other words, the deployment will fail if the Docker image did not pass tests.

Some cautionary notes:

Use outside of Docker

This approach is not limited to Docker. While I have not done so myself, I imagine it could work for publishing builds on an S3 bucket or similar.

How it could work (assuming 0b3da7f is the Git commit SHA of the build, which itself is a .tar.gz file):

  1. Create a bucket with directories builds and tags.
  2. When a build is published, store it in builds/0b3da7f.tar.gz. Create the file tags/built-0b3da7f and store in it the string builds/0b3da7f.tar.gz.
  3. When a build is tested, create the file tags/tested-0b3da7f and store in it the string builds/0b3da7f.tar.gz.
  4. When a build is deployed to staging, create the file tags/deployed-staging-0b3da7f and store in it the string builds/0b3da7f.tar.gz.
  5. When a build is deployed to production, create the file tags/deployed-production-0b3da7f and store in it the string builds/0b3da7f.tar.gz.

To facilitate cleanup, it might be necessary to add the date to each tag, e.g. tags/deployed-production-20210222-0b3da7f, with 20210222 being the current date (February 22nd, 2021). With the date in the tag name, it becomes possible to parse out the date and delete stale builds.

Note last edited November 2023.