Skip to content

Staged rollouts

A staged rollout limits the damage a bad release can do by showing it to a small, representative slice of devices first.

How devices are assigned

Each device identifier is hashed together with the application id, producing a stable number between 0 and 100,000. Ring boundaries are cut from that number, so a device keeps its position across releases and rings are nested: the 5% ring contains the 1% ring. Device groups can override the hash; groups tagged internal are always in the first ring.

Recommended settings

Fleet sizeRingsHold between ringsHalt thresholds
Under 50,00010%, 100%2 hcrash 1.0%, install failure 3%
50,000 to 2M1%, 5%, 25%, 100%6 hcrash 0.5%, install failure 2%
Above 2M0.1%, 1%, 5%, 25%, 100%12 hcrash 0.3%, install failure 1.5%

What halts a release

Each ring is compared against the same devices' behaviour on the previous version. A halt fires when, with at least 400 reporting devices, the crash rate in the first 24 hours after update exceeds the baseline plus your threshold, or install failures exceed the threshold in absolute terms. You can add a custom signal by posting a metric from your own telemetry.

  • A halted release stays at its current ring. Devices that already updated keep the new version unless you publish a rollback.
  • Devices not yet updated continue to be offered the previous version.
  • Channel owners are notified immediately by email or webhook; the reason is attached to the release.

Rollback

Republish the previous version with verdel release rollback acme-notes@2.8.0. Devices on 2.8.0 receive 2.7.3 as a new release with its own delta, and the rollout reuses the same rings in reverse so the most affected devices recover first. Median time from decision to a recovered canary ring is 90 seconds, plus the device polling interval.

If your app can run a migration that makes downgrades unsafe, mark that release no_downgrade. Rollback then ships a new forward version built from the previous code instead.

Schedules

Rings can open at a fixed time in each device's own timezone, for example "Tuesday 10:00 local". Verdel spreads devices over the first hour of the window so a launch does not become a thundering herd at the edge.