Skip to content
AetherAether Docs

Staged rollout

A staged rollout limits a release to a percentage of devices:

Terminal window
aether release-react MyApp ios -r 25

The rollout value is an integer from 1 to 100. Later, widen it with:

Terminal window
aether patch MyApp Staging -r 50
aether patch MyApp Staging -r 100

At 100 the rollout is complete and the release behaves like a full release.

How devices are chosen

Section titled “How devices are chosen”

Selection is deterministic. The server hashes the device’s client id together with the release tag and checks the result against the percentage. The same device stays in or out of a given rollout across checks, so a user does not flap between versions, and each release draws a fresh sample.

Rules

Section titled “Rules”
  • The percentage can only go up. The server rejects a patch that lowers it.
  • A completed rollout cannot be reopened: once a release reaches 100, its rollout can no longer be patched.
  • While the automatic halt has a release disabled, the server refuses to raise its rollout and answers 409 with code set to release_halted. Ship a fixed release or roll back instead. If you decide the halt was wrong, re-enable the release and raise it in one command: aether patch MyApp Production -l v4 --disabled false -r 75. A halt is more than a disable lists the other requests a halt refuses.
  • While the latest release has an unfinished rollout and is still enabled, new releases to that deployment are blocked. The server answers an upload with: Please update the previous release to 100% rollout before releasing a new package. Finish the rollout, or roll back if the release went badly.
  • Promotion can start its own staged rollout in the destination with -r.

Devices outside the rollout keep running the previous release and keep checking in; they join as you raise the percentage.

Automatic halt during a rollout

Section titled “Automatic halt during a rollout”

The same rule that guards a full release also guards a staged one: when the distinct-device signals for the release in rollout cross the thresholds, Aether disables it and emails you. The rollback page describes what halting changes and what it leaves alone.

A lower threshold on the same rule emails you once while the release is still serving, so you can act before Aether disables it. That warning goes out once per release, not once per evaluation window. The email names the app, deployment, and label, and the distinct-device counts behind it. A release that is halted on the same evaluation does not also send that warning. If the warning already went out and the release later reaches the halt threshold, you get the halt email as well.

Only devices inside the rollout install the release, so only they can contribute to its evaluation window. Two thresholds are absolute counts: the distinct devices served and the distinct devices that reported a failure. The third is the failure share among served devices. A rollout that reaches too few devices cannot cross the absolute thresholds, however badly it is going. Raising the percentage increases the population that can contribute.

Halting a release in rollout does not lock the deployment. The unfinished-rollout guard never blocked rollback, and once the release is disabled that guard stops applying too, so you can ship a fix straight away. Landing a rollback on a halted target is a different refusal; see Guards.