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, as does cancelling. A device that downloaded the rolling bundle but has not applied it yet drops it at its next check, such as on a resume (plugin 3.4+). If a launch or resume applies it first (the apply-staged policies, the default at launch), the device runs it once before switching back, as older plugins do.
• 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.

To watch a rollout over time, click the release's channel badge in the bundle row, or choose Activity in its ⋯ menu for the bundle on every channel. The activity chart above the app's device events then shows downloads, applies, errors and rollbacks over time, with each release, rollout step and revert marked, and the rollback share above it. Agents read a release's series with get_release_timeseries.

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.