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 include the most important tools for mobile development pre-installed and ready for use. Our goal is 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.

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

  • Tool upgrade: 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).

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

  • Tool removal: 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).

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

  • Platform changes: Changes to major components, like Xcode on macOS stacks, OS versions, Android SDK.

Using the previous version of a stack

Updating a stack to a new version might cause problems with some builds. To help ease the transition, you can use the previous version of a stack for 2-3 days after an update: Using the previous version of a stack.

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

You can select macOS stacks based on the Xcode version you need. Under the hood, one VM image contains multiple Xcode versions installed and your requested Xcode version is activated at runtime before your Workflow starts.

As a rule of thumb, Xcode minor versions of the same major version share the same VM image, but there might be exceptions based on compatibility issues and other considerations.

Versioning

When talking about versions, we use semver terminology, regardless of how the various tools define their versions.

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

stack-lifecycle.png
  • 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. The stack is still available for yourbuilds but you will see the final removal date on the UI. Preinstalled tools are not updated, so it’s your responsibility to keep up with bugfixes and security patches.

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

Dependency manager cache updates

  • Homebrew and CocoaPods dependency mirrors are updated frequently (usually each week) on all Xcode stacks.

  • These mirror updates do not change the preinstalled tool versions, only updating the package manager caches for faster dependency installs.

  • Edge stacks also receive package upgrades, meaning that Homebrew packages are updated to their latest versions.

State transitions for Xcode stacks

During the lifecycle of a stack it will transition between states when triggered by new Xcode and macOS releases. Stacks transition as follows:

  • Edge to Stable.

  • Stable to Frozen.

  • Frozen to Removed.

Edge stack updates

Edge stacks provide a way to preview and test upcoming changes. Xcode Beta versions become available as Edge stacks while final Xcode releases become available as new Stable stacks. Xcode Edge stacks change when:

  1. The first Beta version of a new major Xcode version is released.

  2. The first Beta version of a new minor Xcode version is released.

  3. A new version of an Xcode Beta version is released.

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. First Beta version of a new major Xcode version

In this example:

  • The current latest Xcode version is 15.3.

  • A new Beta version of a new major Xcode version is released: Xcode 16.0 Beta 1.

stack-updates-edge.png

Once the new Beta version is released, we update our stacks:

  • The new Xcode release becomes available on Bitrise as an Edge stack. In our example, Xcode 16.0 Beta 1 becomes available as the Edge stack.

  • Current Edge stacks are phased out, and users are automatically migrated to the new Edge stack. This happens a few days after the new Xcode release. In this example, this means phasing out Xcode 15.x Edge stacks.

  • Stable stacks are not affected at this point.


Example 2. First Beta version of a new minor Xcode version

In this example:

  • The current latest Xcode version is 15.2.

  • A new Beta version of a new minor Xcode version is released: Xcode 15.3 Beta 1.

stack-updates-edge-minor.png

Once the new Beta version is released, we update our stacks:

  • The new Xcode release becomes available as an Edge stack. In this example, Xcode 15.3 Beta 1 becomes available as an Edge stack.

  • Stable stacks are not affected at this point.


Example 3. A new Beta version of an Xcode Beta version

In this example:

  • The current latest Xcode version is 16.0 Beta 1.

  • A new Beta version is released: 16.0 Beta 2.

stack-updates-edge-beta.png

Once the new Beta version is released, we update our stacks:

  • Xcode 16.0 Beta 2 replaces 16.0 Beta 1 on the Xcode 16.0 Edge stack.

  • Stable stacks are not affected at this point.


Stable stack updates

Stable stacks change less often than Edge stacks as we want to avoid unexpected breaking changes on these stacks.

Existing Stable stacks change when:

  1. A new major Xcode version is released.

  2. A new minor Xcode version is released.

Example 4. A new major Xcode version

In this example:

  • The current latest Xcode version is 15.3.0.

  • A new major Xcode version is released: Xcode 16.0.

stack-updates-stable-major.png

When the new major version is released, we update our stacks:

  • New Stable stack: Xcode 16.0 becomes available on Bitrise as a new Stable stack.

  • Existing Stable stacks: new tool versions and other potentially breaking changes land on all Stable stacks.

  • Oldest Stable stacks become Frozen. In this example, Xcode 14.x stacks become Frozen, but still available for building. Tool versions are not changing on these stacks: their latest state is frozen.

  • Old Frozen stacks are removed: in this example, Xcode 13.x stacks are removed. The remaining users are migrated to newer stacks.

Changes to previous Stable stacks

We update previous Stable stacks when a new Xcode version is released for a number of reasons:

Most preinstalled runtimes and tools eventually reach their end-of-life according to support policy, after which they no longer receive bugfixes and security patches. We also need to periodically upgrade the default version of tools if the majority of our users move on to a newer version. There are also some breaking changes we need to make to enable new features and user requests.

While breaking changes are frustrating, we think that doing them only once a year on a predictable schedule (tied to the major Xcode release) is a good compromise. We are also trying to make the switch smoother by:

  • Offering Edge stacks to preview the changes. While one Edge stack is always tied to the latest Xcode Beta, we also offer Edge stacks for the last few stable Xcodes, so you can try the tooling changes without doing an Xcode upgrade in your project.

  • Communicating the changes in advance on all usual communication channels. For example, in a blog post.

  • Offering a temporary rollback option after each stack update.


Example 5. A new minor Xcode version

In this example:

  • The current latest Xcode version is Xcode 15.2.

  • A new minor Xcode version is released: Xcode 15.3.

When the new minor version is released, we update our stacks:

  • New Stable stack: Xcode 15.3 becomes available on Bitrise as a Stable stack.

  • Xcode 15.3 Edge stack is updated with the final Xcode version.

stack-updates-stable-xcode-minor.png

macOS releases

The exact macOS version is always highlighted on the stack report pages.

When a new major macOS version is released, we upgrade the Edge stacks to the new OS after an internal testing period.

As a general rule, we don’t upgrade macOS on Stable stacks to avoid unexpected build failures. We wait until a future Xcode release starts requiring the new OS version (for example, Xcode 15.0, 15.1 and 15.2 are compatible with macOS Ventura, but 15.3 requires Sonoma). Once this happens, the Stable stack variant of this Xcode version is based on the new major OS version, while older Stable Xcode stacks remain on the older OS version.

While the new major OS is not available as a Stable stack, we recommend testing it on one of the Edge stacks. We are looking for your feedback, including edge cases and performance regressions.

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.

Simulator runtimes on Xcode stacks

You can find the list of preinstalled tools, including simulator runtimes on our stacks on the stack reports pages.

You can expect the following simulator runtimes to be installed:

  • The matching runtime versions of a given Xcode version: these are the iOS, watchOS, tvOS and visionOS runtime versions that Xcode prompts you to download at first launch.

  • For iOS, we also install two additional versions: the two previous major versions, of which the latest minor version is installed.

  • For watchOS, we also install the previous major release’s latest minor version.

For example, when selecting the Xcode 15.0 stack, you can expect:

  • iOS 17.0: the matching runtime of this Xcode.

  • iOS 16.4: the latest minor release of the previous major iOS version.

  • iOS 15.5: the latest minor release of the second-previous major iOS version.

  • watchOS 10.0: the matching runtime of this Xcode.

  • watchOS 9.4: the latest minor release of the previous major version.

  • tvOS 17.0: the matching runtime of this Xcode.

  • visionOS 1.0: the matching runtime of this Xcode

Linux stack updates

Linux stacks on Bitrise are based on Ubuntu LTS releases. Each Bitrise stack is based on one Ubuntu LTS version and never gets upgraded to another. Instead, we release new stacks and sunset older ones over time.

Using the previous version of a stack

Not available on dedicated build environments

This feature is not available on an Enterprise plan with a dedicated build environment, because the user controls the rollout of stack updates on these plans.

We regularly update the Bitrise stacks based on user requests and external tooling changes. These updates can potentially introduce breaking changes, despite our efforts to avoid those.

For those cases, we provide a temporary option to use the previous version of a given stack for a few days after the release of a new version.

  • This is meant to be a temporary mechanism only. Because of infrastructure reasons, we can't keep the previous release available forever. Usually, the previous version is removed a few days after a successful release.

  • Once the previous version becomes unavailable, new builds run on the latest version even if this feature is enabled.

  • If a previous version is not available for a given stack at a given time, the switch is inactive and the feature can't be turned on. Any build triggered will run on the current version of the stack.

To use the previous version of your stack:

Workflow Editor

bitrise.yml

  1. Open your app on Bitrise.

  2. Click the Workflows button on the main page.

    opening-workflow-editor.png
  3. On the Workflows & Pipelines pages, you can:

    • Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.

    • Click the edit-webhook.svg button next to the name of any Workflow to open it in the Workflow Editor.

  4. Go to the Stacks & Machines tab.

  5. Find the stack you want to configure: either the default stack or one of the Workflow-specific stacks.

  6. Under the machine type for the chosen stack, toggle the Use previous version switch.

    This modifies the bitrise.yml file: it adds the previous version of the stack to the meta block.

    prev-vers.png

If you store the bitrise.yml file in your own repository, you need to specify the exact rollback version in a meta object. You cannot use the toggle in the Workflow Editor to turn the feature on because the toggle can only modify a configuration file stored on Bitrise: we cannot edit the bitrise.yml in your repository.

Unavailable versions

If the specified version is not available, the Workflow Editor will display a warning. Any build triggered after a previous stack version becomes unavailable will run on the current stable version of the stack.

  1. Find the meta block in your bitrise.yml file.

  2. Add a stack_rollback_version field with the given version string.

    Finding out the previous version number

    To find out the previous version string, open an older build, switch to the Details & Add-ons tab, and look for the Stack image version field.

    meta:
      stack: osx-xcode-15.0.x
      machine_type_id: g2-m1.8core
      stack_rollback_version: 2-16-2

Changelog

March 2024

New:

  • Define what happens when an Edge stack is phased out in favor of a newer edge stack.

Removed:

  • When a new Xcode Edge stack is released, it no longer brings tooling changes to the Stable stacks.

Changed:

  • New, simpler simulator runtime policy. The same number of older iOS major versions are installed, but only the latest minor version is installed for each.