CircleCI Xcode image release, update, and deprecation policy

This document outlines the CircleCI Xcode image release, update, and deprecation policy. A defined Xcode image policy allows us to continue releasing new images, including beta images.

You can find the most up to date information on these images on the CircleCI Developer Hub Xcode machine image page.

We support the three latest Xcode versions released. We also support the latest minor release of the last four major Xcode versions.

For example, if Xcode 26 is the latest major version:

In the future when Xcode 27 releases:

Apple ships betas of new major versions of Xcode during WWDC, which occurs in June each year.

When we select an image for deprecation and removal, we create an announcement on our changelog, along with additional outreach where possible. We aim to provide four weeks' notice where possible.

We never automatically redirect requests for specific Xcode images to a different major or minor version. When we remove an image, jobs using that image fail if you have not updated the .circleci/config.yml.

We retain the latest patch version of each Xcode major.minor version we support. Once Apple releases a new patch version, we deprecate the previous patch version and automatically redirect all requests to the new patch of the same major.minor version.

Patches are generally backwards compatible, so we put redirects in place within 24 hours of a new patch release. If we discover any major issues, we retain the ability to issue a rollback and make both versions temporarily available.

Example:

When Apple released Xcode 13.2.1, we removed the previous patch version, 13.2.0, and automatically redirected all requests for 13.2.0 to 13.2.1.

We aim to make beta Xcode versions available on the macOS executor as soon as we can. This allows developers to test their apps ahead of the next stable Xcode release.

Unlike our stable images (which we freeze once released), when we release a new beta image it overwrites the previous beta image until we release an RC/Stable image. At that point we freeze the image and no longer update it. If you request an image using an Xcode version currently in beta, it changes when Apple releases a new Xcode beta with minimal notice. This can include breaking changes in Xcode and associated tooling which are beyond our control. We do not recommend beta images for production pipelines.

To read about our customer support policy for beta images, check out this support center article.

We track and monitor Apple’s Xcode releases and aim to release new images as soon as possible. We typically aim to support a new Xcode image within a couple of days, but note that this is not an SLA. We do not provide an official SLA turnaround time for new Xcode images.

We always announce new images on our changelog along with release notes. We also add them to the table of Xcode Versions in the Documentation.

We build each Xcode image on top of a clean macOS install. We aim to keep the macOS version reasonably up to date with the latest version available. Generally our images can be up to 2 minor/patch versions behind the latest stable version.

We aim to keep the macOS version aligned across our different macOS executors. Note that this may not always be the case. Check the Software Manifest file for the image for the most accurate information.

When Apple releases a new major version of macOS (ex: 27.0), we start to use this version after at least two minor Xcode releases have passed.

At any time, we reserve the right to work outside of the information in this document if the circumstances require. When we need to make an exception to the policy, we aim to provide as much notice and clarity as possible. In these cases, we post an announcement on our Discuss forum, along with additional outreach, such as an email notice, where possible.