Percentage Rollouts

Release a bundle to a share of devices first — for example 10% of production — check its health, then raise the share or complete the rollout. If it misbehaves, cancel it and every device returns to the previous release.

Rollouts need @otakit/capacitor-updater 3.1 or later on the device. Channels choose who gets a release (testers, beta, production); rollouts choose how many of them get it.

How devices are selected

• Each installation keeps a random secret that never leaves the device. For every rollout it derives a number from 1 to 100 and takes the rolling release when that number is within the percentage.
• The number stays the same for the whole rollout. Raising 10% to 25% adds devices; lowering it moves the extra devices back to the previous release after their next check. A device that already downloaded the rolling bundle may run it once more before switching back, which also applies when a rollout is cancelled.
• Each rollout draws new numbers, so the same devices are not always first.
• No device identifiers are collected. The percentage and the rolling release are part of the signed manifest.
• Devices on plugin versions before 3.1 ignore rollouts and stay on the previous release until the rollout completes.
• The first release on a channel goes to every device, since there is nothing to fall back to.

Start a rollout

Pass --rollout when you release. In the dashboard, choose the share under Roll out to in the release dialog.

# Upload and release to 10% of production
otakit upload --release production --rollout 10

# Or roll out a bundle you already uploaded
otakit release <bundle-id> --channel production --rollout 10

Raise, complete, or cancel

otakit rollout                                    # show active rollouts
otakit rollout --channel production --percent 50  # raise or lower the share
otakit rollout --channel production --complete    # every device gets it
otakit rollout --channel production --cancel      # everyone returns to the previous release

In the dashboard, open the channel badge of the rolling bundle for Change percentage, Complete rollout, and Cancel rollout. A completed rollout is final; to undo it, revert the release.

Releasing during a rollout

A channel has one rollout at a time. Releasing another bundle while one is rolling out is refused, so a rollout is never replaced by accident. Complete or cancel it first, or pass --replace-rollout to cancel it and release the new bundle in its place:

otakit upload --release production --replace-rollout --rollout 10

Health and auto-revert

Devices on the rolling release report events with its own release ID, so its health counts only those devices. Auto-revert works on rolling releases and returns every device to the previous release. At low percentages it takes longer to reach the minimum sample, so small apps should start at 5% or more.

On the device

getState().rollout shows what the last check saw, which helps when testing a rollout on a phone:

const { rollout } = await OtaKit.getState();
// { releaseId, version, percent: 10, bucket: 57, included: false }, or null

API and agents

The REST API takes rolloutPercent and replaceRollout when releasing and has an endpoint to change the percentage; see the REST API. Agents use publish_release with rolloutPercent and set_rollout_percent; see MCP & Agent Skills.