CircleCI convenience images support policy

This document outlines the CircleCI Docker convenience images release, update, and deprecation policy.

This policy applies to all CircleCI convenience images we publish to the cimg namespace on Docker Hub.

Our Docker convenience images are all built upon our base image, cimg/base. This image is in turn built upon the official Ubuntu Docker image.

We aim to build variants of this image for all LTS versions of Ubuntu that are being maintained in “Standard Support” status. We will stop building variants of cimg/base with Ubuntu LTS versions that drop out of support.

When a new Ubuntu LTS version is released, the child CircleCI convenience images will have the underlying base image switched to this version around 6 months after the first release of the cimg/base variant.

By building all of our convenience images on top of a common image, we increase the chance of the underlying base layers being cached by the execution environment, therefore increasing the spin up speed for the job.

We build a new base image each month. However, we only update the base image used in child convenience images once per quarter. These updates are not retroactively applied to existing images, but will apply to new releases of the image after the change has been made.

We encourage users who are building their own images for use on CircleCI to use our cimg/base image as a starting point.

We track new releases of languages and aim to provide new convenience images that support these new releases within 48 hours. This is not an SLA (service level agreement). We can not, and do not, provide an official SLA turnaround time for new convenience images.

For our deployment focused images, we provide a new image once per month.

We do not provide new image releases for alpha, beta, preview or release candidates of languages.

Each image is tagged with the specific major.minor.patch version of the language it contains. We also provide major.minor tags, which always point to the latest patch release of the image.

In special cases, we also provide additional tags, such as lts or current, which track releases as per the tagging scheme of the parent project.

We do not provide a latest, or current, tag for any convenience images, other than special cases as mentioned above. This is by design, and is not something we have plans to implement in the future. We do this to ensure that jobs based on our images are more deterministic in nature, with minimal changes due to us pushing new tags that switch current to a new major version, for example. This helps lower the risk of breaking changes occurring when customers have not explicitly updated their configurations.

When critical CVEs are disclosed that affect the versions of the operating system or software stack in our convenience images, we will investigate the impact that this has on our images being used within CircleCI execution environments.

In most cases, due to the ephemeral and isolated nature of the containers in the environment, it is not necessary to patch these images. We will always communicate our stance on these disclosures on our Discuss Forum.

We welcome bug reports and PRs from our community via GitHub for each image. The GitHub repository for each image can be found by visiting the Developer Hub.

As a general rule, minor, non-blocking bugs will be fixed in the next release of the image. For major/blocking changes, we will patch the existing live image, depending on how old the image is.

For issues and PRs that are requesting new features in the image, we ask that justification and scope is provided. Keeping the images small in size and simple to build, whilst providing the most functionality is our main aim.

While we make every effort to respond to issues and PRs in a timely manner, we do not provide an official SLA for this.

We generally do not remove images from Docker Hub once published, however we encourage customers to follow the projects for the languages they use and update the images in their jobs once the project declares a version as EOL (end-of-life).

For versions that are EOL, we do not issue bug fixes or patches.

​​At any time, we reserve the right to work outside of the information in this document if the circumstances require. In the event that we are required to make an exception to the policy, we will aim to provide as much notice and clarity as possible. In these cases, an announcement will be posted on our Discuss Forum, along with additional outreach, such as an email notice, where possible.