This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Learn how to incrementally deploy updates to your users by using a rollout mechanism.

A rollout allows you to roll out a change to a portion of your users to catch bugs or other issues before releasing that change to all your users.

EAS provides per-update and branch-based rollout mechanisms depending on your use case.

Per-update rollouts

This rollout mechanism allows you to specify a percentage of users that should receive a new update when you publish it, and then increase that percentage gradually afterwards.

Starting

To start an update-based rollout, add the --rollout-percentage flag to your normal eas update command:

In this example, when published, the update will only be available to 10% of your end users.

Progressing

To edit the percentage of an update-based rollout:

You will be guided through the process of selecting the update to edit and asked for the new percentage.

Ending

When ending an update-based rollout, you have three options:

• Finish the rollout: Use eas update:edit to increase the rollout percentage to 100.
• Revert the rollout: Use eas update:revert-update-rollout to restore the control update.
• Replace the rollout: Publish a new update or roll back to the update embedded in the build. See Publishing while a rollout is in progress.

Publishing while a rollout is in progress

You can replace an active rollout if you need to publish a fix or roll back before the rollout finishes. When you publish to the same branch, platform, and runtime version, EAS CLI shows the active rollout and stops without publishing.

To end the rollout and publish, add --force-end-active-rollout. For example, use the following command to publish a fix:

To roll back to the update embedded in the build instead:

You can use the flag with eas update, eas update:republish, eas update:roll-back-to-embedded, and eas update:rollback.

--force-end-active-rollout requires EAS CLI 24.9.0 or later.

The active rollout continues until the new update is ready. If you use code signing, the rollout ends after EAS CLI signs the new update.

When the rollout ends, the new update becomes available to all users on the matching branch, platform, and runtime version. Each user's app downloads and launches it according to the app's update behavior. If you publish a rollback to embedded, each user's app returns to the update embedded in its build instead.

Replacing a rollout keeps the rollout update group and its dashboard links. Reverting a rollout with eas update:revert-update-rollout deletes the rollout update group.

You cannot replace an active rollout with another rollout. To publish a new update with --rollout-percentage, first finish the active rollout with eas update:edit or revert it with eas update:revert-update-rollout.

Additional notes

• Only one rollout can be in progress for a given branch, platform, and runtime version.
• To see the state of the rollout, use the eas update:list or eas update:view commands.
• Reverting a rollout that is created on a branch with an existing update will republish the control update. This ensures that all clients are reverted back to the previous state.
• A rollout can be started on a branch with no current update, in which case the first update will be rolled out to the specified percentage of users. When reverted, a rollback-to-embedded update will be created, which will revert the clients to their previous state (embedded update).

Branch-based rollouts

This rollout mechanism allows you to incrementally roll out a set of updates on a new branch to a percentage of end users and leave the remaining percentage of users on the current branch.

Starting

To start a branch-based rollout, run the following EAS CLI command:

In the terminal, an interactive guide will assist you in selecting a channel, choosing a branch for the rollout, and setting the percentage of users for the rollout. To increase or decrease the rollout amount, run the command again and choose the Edit option to adjust the rollout percentage.

Ending

Two methods are available to end a rollout when you choose the End option in the interactive guide:

• Republish and revert: Use this option when you are confident with the state of the new branch. This will republish the latest update from the new branch to the old branch, and all users will be pointed to the old branch.
• Revert: Choose to disregard the updates on the new branch and return users to the old branch.

Additional notes

• Only one branch can be rolled out on a channel at a single time.
• To see the state of the rollout, use the eas channel:rollout command.
• When a rollout is in progress, you can publish updates to both rolled out and current branches by running eas update --branch [branch], for example.
• eas update --channel [channel] cannot be used when a rollout is in progress since it cannot know which branch in the rollout to associate the update with.