Documentation structure for LLMs (llms.txt)
CircleCI Logo

CircleCI Xcode image release, update, and deprecation policy

5 minutes ago
Cloud

Overview

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.

Xcode image retention and deprecation

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 27 is the latest major version:

Xcode retention policy example
Xcode Version Action

Xcode 27

We retain the three latest major.minor versions at the latest patch version

Xcode 26

We retain the latest major.minor version

Xcode 16

We retain the latest major.minor version

Xcode 15

We retain the latest major.minor version

Xcode 14

We flag this version for deprecation and remove it 30 days after we announce the deprecation

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

Deprecation notice and retention period

Once we select an Xcode image for deprecation, we retain it for 30 days before we remove it.

We announce the deprecation through the following channels:

  • The CircleCI changelog.

  • An in-app banner, shown to the organizations and jobs affected by the deprecation.

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 your CircleCI configuration file.

Brownouts

During the 30-day retention period, we schedule brownouts. A brownout is a temporary, planned period when we make a deprecated image unavailable on purpose. Jobs that use the image fail during a brownout. This warns you before we remove the image for good.

For more information about how brownouts work and how to respond to them, see the Image Brownouts section of the image lifecycle page.

Xcode patches

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

Patches are generally backwards compatible, so we put redirects in place within 24 hours of a 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.

Beta image support

We aim to make beta Xcode versions available on the macOS executor at the earliest opportunity. 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 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 subsequent 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.

Xcode image releases

CircleCI commits to providing Xcode image updates within 2 business days of Apple’s official GA release, as announced on Apple’s official RSS feed. This commitment applies to stable, generally available Xcode releases only.

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

Exceptions to the release window

Pre-release builds

Beta releases and release candidates are not subject to the 2 business day commitment. We publish Beta and RC images on a best-effort basis with no guaranteed timeline. See Beta image support for more detail.

macOS upgrade required

For major Xcode releases that require a corresponding macOS upgrade on our fleet, the standard 2 business day window does not apply. We aim to publish a projected availability date within 5 business days of Apple’s GA release. We post a notice on our changelog when the image goes live.

Image quality hold

In rare cases, CircleCI’s validation process may identify critical issues with a newly released Xcode image. Examples include:

  • Toolchain regressions.

  • Simulator instability.

  • Build system defects introduced by Apple.

When this occurs, we may delay availability beyond the standard window. We aim to post a notice on our changelog within the original 2 business day window. The notice states that the release is under a quality hold. It also states whether Apple or CircleCI caused the issue. Once we know the scope of the fix, we share a projected timeline.

macOS versions

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.

Exceptions

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 changelog.