CircleCI Xcode image release, update, and deprecation policy

This document outlines the CircleCI Xcode image release, update, and deprecation policy. By having a defined Xcode image policy, we are able to continue releasing new images quickly, including beta images.

You will 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. In addition, we will always support the latest minor release of the last four major Xcode versions.

For example, with Xcode 16 being the latest major version being released:

Future example, when Xcode 26 is released:

Betas of new major versions of Xcode are shipped by Apple during WWDC, which usually occurs in early-mid June each year.

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

We will never automatically redirect requests for specific Xcode images to a different major or minor version. When an image is removed, jobs using that image will fail if the .circleci/config.yml has not been updated.

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

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

Example:

When Xcode 13.2.1 was released, 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 will allow developers to test their apps ahead of the next stable Xcode release.

Unlike our stable images (which are frozen once released), once a new beta image is released it will overwrite the previous beta image until an RC/Stable image is released. At that point the image is frozen and no longer updated. If you are requesting an image using an Xcode version that is currently in beta, it will change 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 using beta images for production pipelines.

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

We closely track and monitor Apple’s Xcode releases and always aim to release new images as quickly as possible. Typically we aim to support a new Xcode image within a couple of days, however note that this is not an SLA. We can not, and do not, provide an official SLA turnaround time for new Xcode images.

New images are always announced on our changelog along with release notes, and will be added to the table of Xcode versions in the documentation.

Each Xcode image is built 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, however this may not always be the case. Check the Software Manifest file for the image for the most accurate information.

When a new major version of macOS (ex: 26.0) is released, we will start to use this version after a minimum of 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. 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.