Skip to main content

Stack update policy

Abstract

Bitrise stacks are updated every week: some stacks are completely rebuilt while on others only certain cache archives are updated.

Bitrise stacks have many important tools preinstalled to make workflows simple and make your builds fast and efficient. These tools change continuously: old versions become deprecated and unsupported while new versions are released with new features and breaking changes. Everyone has different expectations for when and how the underlying stacks are updated with these tools. Some users prefer the least possible change to maximize stability, while others want to adopt the latest releases as soon as possible.

Stacks on bitrise.io are updated regularly. The updates contain one or more of the following kinds of changes:

  • An already installed tool is upgraded to the latest version (for example, the git CLI is upgraded from 2.9.1 to 2.9.5).

  • A new tool is added (for example, the latest Android emulator system image becomes preinstalled when a new Android version is released).

  • A tool version is removed if it reaches end-of-life and poses a security risk, making another version of the tool the default (for example, Ruby 2.7 is removed, making Ruby 3.0 the new default).

  • On Xcode stacks, the local caches of Homebrew and Cocoapods are updated with the latest snapshot.

For more information on what tools are available on the different stacks, check out our relevant guide: Preinstalled tools on Bitrise stacks.

Xcode stack updates

We divide our Xcode stacks into categories based on OS, CPU architecture, and Xcode versions. For example, we have a stack for macOS 13 Ventura on M1, which includes Xcode 14.2, Xcode 14.1, and Xcode 14.0.

Stacks have a lifecycle and have four different states - Edge, Stable, Frozen and Removed.

  • Edge: These stacks are for previewing upcoming versions and changes. They are updated in-place regularly, and they include the latest stable release of Xcode, the latest beta release of Xcode (if available), the latest stable version of pre-installed tools, and the dependency manager cache updates. Regular weekly updates could add or remove tools, as well as upgrade the OS. Backwards compatibility for weekly updates is not guaranteed on an Edge stack. Run builds on Edge stacks to preview upcoming tool version changes (such as Ruby 3.2 becoming the default) and get access to the latest pre-release Xcode (such as Xcode 15 Beta).

  • Stable: These stacks are only updated with Xcode patch versions, dependency manager cache updates and with critical security fixes. Note that one specific stack that is in a stable state (for example, Xcode 14.3) could still receive a major update when a new Edge stack is released (a hypothetical Xcode 14.4 Beta) and the tool versions on the current Edge stack become the new Stable. For maximum reliability and reproducible builds, we recommend pinning exact tool versions in Workflows instead of relying on the stack defaults (for example, pinning a Ruby version).

  • Frozen: These stacks are no longer updated and flagged for removal in accordance with the Stack deprecation and removal policy.

  • Removed: These stacks are no longer available to use.

Pinning an Xcode version

Whenever a new Xcode version comes out, we make sure it's available for our users within two working days.

About dependency manager cache updates

All Xcode stacks receive a dependency manager cache update (Homebrew, CocoaPods) every week. These cache updates do not change the pre-installed tool versions, they only update the package manager caches for faster dependency installs.

State transitions for Xcode stacks

During the lifecycle of a stack it will transition between states. Stacks transition from Edge to Stable, Stable to Frozen, and Frozen to Removed. Transitions are triggered by new Xcode and macOS releases. When a set of stacks transition from Edge to Stable, it also has tooling changes that we introduced to the Edge stacks first as a preview.

Transitioning from Edge to Stable state

The purpose of the Edge stacks is to provide a preview of upcoming changes that will be included in the next transition. Edge stacks transition to Stable when:

  1. An Xcode minor GA (General Availability) version is released: this Xcode version becomes available as a Stable stack and the tooling version changes on Edge stacks are applied to the Stable stacks.

  2. An Xcode major GA version is released: this Xcode becomes available as a Stable stack and the tool changes on Edge stacks are applied to the Stable stacks.

  3. A Xcode major beta version is released: this beta Xcode version becomes available as an Edge stack, replacing the previous Edge stacks. The tooling version changes on the previous Edge stacks are applied to the Stable stacks.

When an Xcode minor version is released as a beta, it becomes available as an Edge stack. Other Edge stacks do not transition to Stable until the beta version in question is released as a GA version.

Example 1. Xcode minor GA version release

When Xcode 14.4 GA is released:

  1. The Xcode 14 Edge stacks are updated with the GA version of Xcode 14.4.

  2. Xcode 14.4 becomes available as a Stable stack.

  3. All existing Xcode 14 Stable stacks are overwritten with the latest Edge stack equivalents.

  4. The following week, Stable stacks will only receive the regular dependency cache updates, while Edge stacks will receive tool updates too.

transition-stack.png

Example 2. Xcode major beta version release

When Xcode 15.0 Beta 1 is released:

  1. A new Xcode 15.0 Edge stack is created.

  2. The existing Xcode 14 Stable stacks are removed and the Xcode 14 Edge stacks transition and take their place.

  3. The Xcode 13 stacks are now Frozen and no longer receive updates.

transition-stack-2.png

Example 3. Xcode major GA version release

When Xcode 15.0 GA is released:

  1. The Xcode 15.0 Edge stack is updated with the GA version of Xcode 15.

  2. A new Xcode 15.0 Stable stack becomes available.

transition-stack-3.png

Transitioning to Frozen and Removed states

Stacks transition from Stable to Frozen and Frozen to Removed states as outlined in our stack deprecation and removal policy.

macOS releases

When new major macOS versions are released, the latest major Xcode version stacks running on the previous version of macOS will be flagged for removal.

The date of the actual removal depends on factors such as performance, stability, and internal testing results of builds on the new macOS version. There will be a minimum of four weeks notice provided for the removal of these stacks.

Example 4. macOS 13 Ventura

When macOS 13 Ventura was released, the Xcode 14.0 and 14.1 stacks were made available on both macOS 12 Monterey and macOS 13 Ventura.

The Xcode 14.0 and 14.1 Monterey stacks were flagged for removal and customers were asked to migrate their workflows to Ventura based stacks because this version solved issues with hanging builds.


Events not triggering a state transition

Not all Xcode releases trigger a transition. For example, Xcode beta minor version releases do not trigger an Edge to Stable stack transition: the new beta version simply replaces the old one. Xcode patch releases do not trigger an Edge to Stable stack transition. Instead, the Stable stacks will be updated in place with the new patch version.

Available simulator runtimes on Xcode stacks

Our policy for available simulator runtimes on Xcode stacks is based on Apple's minimum requirements and supported SDKs.

Preinstalled tools on Bitrise stacks

If you are interested in the list of preinstalled tools, such as simulator runtimes on our stacks, you can find every available stack’s stack reports.

For each major version of Xcode we provide:

  1. All of the minor versions for the latest major simulator version.

  2. The most recent minor version from the previous major simulator version.

  3. The most recent minor version from the penultimate major simulator version.

Example 1. Available iOS simulators on Bitrise stacks

Let's look at an example:

Xcode 12.5 has minimum requirements to work with iOS 10.3.1-14.5 simulator runtimes. The 14.5 simulator runtime is the latest version, so we make it available across all stacks. In this case, the 14.5 simulator is compatible with all our currently active Xcode stacks and so it is available on all those stacks.

Xcode 13.0 has minimum requirements to work with iOS 10.3.1-15.0 simulator runtimes. The 15.0 simulator runtime is the latest version, so just like for iOS 14.5, we make it available for all compatible stacks, which is all of them except for Xcode 12.5.

We continue going through all Xcode versions and taking the latest supported simulator runtime until the last Xcode version, which is Xcode 14.2. When we are done, we also take the most recent version of the iOS simulator runtime prior to the oldest major version. In this case, the oldest major version is iOS 14.5, and the most recent iOS simulator prior to that is iOS 13.7, so that version will also be available for all stacks.

This table illustrates which iOS simulator runtimes are available for which Xcode version on our macOS stacks:

Table 1. Available simulator runtimes for iOS (X = available)

Simulator

Xcode 14.2

Xcode 14.1

Xcode 14.0.1

Xcode 13.4.1

Xcode 13.3.1

Xcode 13.2.1

Xcode 13.1

Xcode 13.0

Xcode 12.5

iOS 16.2

X

iOS 16.1

X

iOS 16.0

X

X

X

iOS 15.5

X

X

X

X

iOS 15.4

X

X

X

X

X

iOS 15.2

X

X

X

X

X

X

iOS 15.0

X

X

X

X

X

X

X

X

iOS 14.5

X

X

X

X

X

X

X

X

X

iOS 14.4

iOS 14.3

iOS 14.2

iOS 14.1

iOS 14.0

iOS 13.7

X

X

X

X

X

X

X

X

X

iOS 13.6

iOS 13.5

iOS 13.4

iOS 13.2

iOS 13.1

iOS 13.0



The Android & Docker stacks

The Android / Linux stacks are prepared with docker, using multiple separate docker images built on top of each other.

In this section:

A build stack indicates the full configuration of the virtual machine that Bitrise uses to run your build. Each stack includes an operating system, and a large number of pre-installed software and tools. For example, our Xcode stacks run on macOS operating systems and contain, among many other tools, the Xcode version that is indicated in the name of the stack.

A build stack indicates the full configuration of the virtual machine that Bitrise uses to run your build. Each stack includes an operating system, and a large number of pre-installed software and tools. For example, our Xcode stacks run on macOS operating systems and contain, among many other tools, the Xcode version that is indicated in the name of the stack.