Release channels

The Tuist CLI ships through three channels with different stability guarantees. The recommended install is stable and moves slowly: it does not advance every time a feature merges, so upgrading no longer means absorbing a batch of unrelated changes. Early adopters can still run per-commit builds on canary, and the release candidate channel lets teams soak an upcoming line before it becomes stable.

The channels#

Channel	Version format	Cadence	Resolved by default?
Canary	`X.Y.0-canary.N` (e.g. `4.201.0-canary.42`)	Every commit to `main`	No — explicit opt-in
Release candidate	`X.Y.0-rc.N` (e.g. `4.200.0-rc.1`)	Cut from `main`, soaks ~1 week	No — explicit opt-in
Stable	`X.Y.Z` (e.g. `4.200.0`, `4.200.1`)	Promoted after a clean soak	Yes

Canary and release candidate builds are published as prereleases. Tools like Mise and Homebrew exclude prereleases when resolving latest, a bare install, or a line pin, so you only ever land on one of them by asking for it explicitly.

Canary#

Every commit to main publishes a canary. Canary always represents the next unreleased minor: once a line is cut for release, main advances to the following minor (for example, from 4.200.0-canary.42 to 4.201.0-canary.1). Canary is the right channel for early adopters who want the earliest possible signal, or to verify that a fix you reported or contributed behaves as expected before it reaches stable.

Release candidate#

When a minor is ready to ship, its line is frozen onto a protected releases/<major>.<minor>.x branch and published as X.Y.0-rc.1. The line is feature-frozen; only critical fixes and regressions are cherry-picked, and each accepted fix increments the RC (-rc.2, -rc.3, …). After the soak period concludes cleanly, the line is promoted to stable.

Stable#

Stable is the recommended channel and the one all documentation points to. A stable minor (X.Y.0) is published only when a release candidate has soaked cleanly, and it does not advance when new features merge to main. Patches (X.Y.1, X.Y.2, …) on a stable line contain backported fixes only, never new features.

Choosing a version#

With Mise (recommended):

bash

mise use tuist@latest              # Latest stable (recommended)
mise use [email protected]               # Pin to a stable line; receives backported fixes only
mise use [email protected]             # Pin to an exact stable patch
mise use [email protected]        # Opt into a release candidate to soak it
mise use [email protected]   # Opt into a specific canary build

With Homebrew, brew install --formula tuist always installs the latest stable; prereleases are not distributed through the formula.

Recommended strategy#

Pin to a stable line, for example [email protected]. That line receives only backported fixes, never new features, so day-to-day upgrades stay low-risk.
Adopt new features deliberately. When you are ready for the next minor, soak it on the release candidate channel, then move your pin to the new stable line.
Try canary in a non-critical environment if you are an early adopter who wants the earliest possible signal.

Support and backports#

Two stable lines are actively maintained at any time:

Line	Receives
Current (`X.Y.x`)	Regressions and security fixes
Previous (`X.(Y-1).x`)	Critical and security fixes only
Older	None — upgrade to a maintained line

Fixes land first on main (canary). Regressions and security fixes are backported to the current stable line, and the previous line receives critical and security fixes only. Other bug fixes are not backported; they ship with the next minor. When a new line is promoted to stable, the line that was current becomes "previous", and the line that was "previous" stops receiving backports.

Independently of the channel, the Tuist server stays compatible with any CLI released in the last 3 months, so pinning to a stable line never puts you outside the supported window as long as you upgrade within that period.