Specifying Docker image versions on 2.0


With the Docker executor, we highly recommend using an immutable identifier to specify your Docker images. Two ways are shown in this example .circleci/config.yml:

version: 2
executorType: docker
  - image: ruby:2.3.1
  - image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673
  1. Use an immutable tag. Tags like 2.3.1 are only immutable by convention. When you need to change your image, create a new tag (i.e. ruby:2.3.2) and keep your old and new tags immutable.
  2. Use a SHA tag–these are inherently immutable.


Tags in Docker can change what SHA they refer to. The most common case of this is latest, but also master and other branch names change meaning over time.

This article from Container Solutions is a great write-up of why latest is to be avoided. Their argument extends to mutable tags as well.

Mutable tags will generally create headaches for you and your team. But, you should be more mindful of this when running your builds on a cloud-based platform like CircleCI 2.0. You have no control over which machine runs your builds. Your next build might run on the same machine or a totally different one. Without such guarantees, using mutable tags will lead to unpredictable builds.

Correctly update primary container image