Release channel hierarchy

Opentrons desktop apps on Flex and OT-2 use electron-updater with three stability channels: alpha, beta, and stable (latest). Each channel reads a YAML manifest on the build CDN (alpha.yml, beta.yml, latest.yml). This page explains the traditional release model those channels reflect, why the YAML files overwrite each other the way they do, and how we still ship different build flavors on alpha and beta in parallel.

The traditional release model

Most software teams treat prerelease quality as a hierarchy of confidence:

Alpha builds go to a small, controlled audience first. The goal is early feedback and shaking out obvious defects before wider exposure.
When alpha builds reach enough stability, a beta build is published to a larger customer set. Beta is still prerelease, but it represents higher confidence than alpha.
Testing continues. Teams may ship further alpha builds for narrow validation and further beta builds for broader soak testing until both channels meet their quality bars.
When confidence is high enough, a stable release replaces prerelease channels for general availability.

That ladder is why electron-updater exposes separate channel YAMLs and a setting (generateUpdatesFilesForAllChannels) that writes lower-stability metadata when a higher-stability build publishes: a stable release should be visible to everyone who opted into beta or alpha, and a beta release should not leave alpha users stranded on an older build when beta is strictly ahead.

How YAML overwrite preserves the hierarchy

When a desktop build publishes, electron-updater updates one or more YAML files on the CDN. Higher-stability publishes overwrite metadata for lower channels:

Stable release

latest.yml
beta.yml
alpha.yml

Beta release

latest.yml (unchanged)
beta.yml
alpha.yml

Alpha release

latest.yml
beta.yml
alpha.yml

Key behavior (asymmetric by stability):

Beta publish writes beta.yml and also overwrites alpha.yml with the beta build. latest.yml is unchanged.
Alpha publish writes alpha.yml only. It does not overwrite beta.yml or latest.yml. An alpha publish after a beta publish restores alpha.yml to the alpha build.
Stable publish writes all three: latest.yml, beta.yml, and alpha.yml.

Configured in opentrons/app-shell/electron-builder.config.js via generateUpdatesFilesForAllChannels: true. Higher-stability publishes cascade metadata to lower channels so prerelease users are not stranded on older builds when a higher channel moves forward.

This applies on every Opentrons app host that serves desktop updater YAMLs, including Flex internal (ot3-development.builds.opentrons.com), Flex external (builds.opentrons.com), OT-2 internal (ot2-development.builds.opentrons.com), and OT-2 external (ot2.builds.opentrons.com).

Publish order vs tag order

Git tag push order and desktop build publish order are separate. Tags at the same semver base can be created in any order. Alpha and beta are independent tag lanes; either lane can move forward first.

Updater YAML pointers follow which desktop build finished publishing last, not which tag was created first. Artifact URLs in releases.json keep every published version; only the channel YAML files (alpha.yml, beta.yml, latest.yml) are overwritten on publish.

Real example (internal Flex 4.0.0): ot3@4.0.0-alpha.4 was tagged on 2026-06-17 and ot3@4.0.0-beta.1 on 2026-06-22. Both builds remain in releases.json, but alpha.yml currently points at 4.0.0-beta.1 because the beta desktop publish ran after alpha with no follow-up alpha publish to restore alpha.yml. Alpha-channel users see the beta build until a new alpha desktop publish completes.

Parallel flavors, not only a straight ladder

The hierarchy above describes who should receive which build through the updater. Our release process also needs flexibility: alpha and beta can carry different build flavors at the same time, not only a single line that always promotes alpha → beta → stable.

Example: a beta build may target VM isolation validation while a separate alpha build targets CRS, both active during the same development cycle. That is normal. The updater hierarchy still applies to metadata on the CDN; it does not require every alpha to become the next beta before either channel moves forward.

When both alpha and beta need fresh builds

If you intend to update both channels in the same release cycle, publish desktop builds in this order:

Beta first (overwrites beta.yml and alpha.yml)
Alpha second (restores alpha.yml only; leaves beta.yml on the beta build)

Do not stop after step 1. Beta alone leaves alpha-channel users on the beta build. Step 2 is required whenever alpha and beta are distinct builds at the same semver base.

That ordering rule is about desktop build publish order, not git tag order. Tags can be pushed in either sequence. It also does not mean alpha must always precede beta in development. It ensures alpha.yml ends on the intended alpha build after both channels update.

Failure risk

Beta after alpha (without a follow-up alpha publish): the common failure mode. Beta overwrites alpha.yml; alpha artifacts stay in releases.json but alpha-channel users follow alpha.yml and see the beta build.

Alpha after beta: not a failure mode for beta users. Alpha restores alpha.yml only and does not change beta.yml.

If a beta publish succeeds but the follow-up alpha publish fails or is skipped, alpha-channel users keep seeing the beta build until alpha metadata is restored. Treat a paired cycle as incomplete until:

Beta artifacts and beta.yml point at the intended beta build
Alpha artifacts and alpha.yml point at the intended alpha build
You have verified both YAML URLs on the correct pipeline host

Stable releases

A stable desktop publish updates latest.yml, beta.yml, and alpha.yml. Users on any prerelease channel who are eligible for stable will see the stable build through the same hierarchy. Plan stable only when alpha and beta validation for that cycle is complete.

Summary

Traditional model: alpha (narrow) → beta (broader) → stable, with iteration on alpha and beta until confidence is high enough.
YAML cascade (one-way): beta overwrites alpha.yml; alpha restores alpha.yml only and does not touch beta.yml; stable overwrites all three.
Tag order ≠ publish order: tags can be pushed in any sequence; YAML pointers follow the last desktop build publish.
Parallel flavors: alpha and beta can represent different active build lines; the hierarchy governs updater metadata, not a single mandatory promotion path.
Paired cycle: when both channels need new builds, publish beta then alpha so alpha.yml ends on the correct build.
Flex and OT-2: same channel filenames and overwrite rules on internal and external app hosts.