update channels and rollouts

35 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Override persistence behavior

The override set by Updates.setUpdateRequestHeadersOverride() persists on the device. After it is set, future update checks use the selected channel until the app clears or replaces the override, or until the app is uninstalled.

Test channel surfing with APK or simulator builds

To test channel surfing locally, install a release build that points to the starting channel. For local testing, you can use an Android APK build or an iOS Simulator build instead of building through EAS Build.

Channel surfing in EAS Update

Channel surfing allows you to switch update channels in non-development builds at runtime. This achieves the same functionality as CodePush's staging environment testing, allowing non-technical stakeholders to test features from a single build. Development builds can load updates from any compatible channel.

EAS Update streams organization

EAS Update organizes updates using two types of streams: branches (corresponding to source control branches) and channels (which point to branches). Builds point to channels, not branches. A channel can point to different branches for each runtime version and support incremental rollouts. This separation prevents development and staging branches from automatically going to production users.

Channel configuration for EAS Update

Channels indicate which environment the update targets, such as 'production' or 'staging'. Each build profile should point to a channel of the same name. The default configuration from eas update:configure will create a production profile pointing to the production channel and a staging profile pointing to the staging channel. If using EAS Build, the default configuration also includes a preview profile pointing to the preview channel with internal distribution.

Deploy staging updates with eas update command

Run 'eas update --channel staging' to publish an update to staging. This makes the hotfix immediately available to users of staging builds with the targeted runtime version. Staging should use the beta track on respective app stores (Google Play Beta or TestFlight), or alternatively internal distribution.

When to use internal distribution for preview builds

Preview builds can use internal distribution for cases where you want to share a build on every pull request or distribute early concepts without formal beta testing. Internal distribution reduces friction compared to store beta tracks but requires users to download from an expo.dev URL.

Unexpected branch in deployment

If the deployment has an unexpected branch, the channel must be mapped to the correct branch using the eas channel:edit command.

Missing branch in deployment

If the displayed deployment has the correct channel but is not linked to a branch, the channel must be mapped to the correct branch using eas channel:edit.

Channels page location

The Channels page is located at https://expo.dev/accounts/[account]/projects/[project]/channels. It displays channel names and channel to branch mappings if they exist.

Verify channel to branch mapping

A link between a channel and a branch is defined by the developer. When a channel and branch are linked, an app with that channel will get the most recent compatible update on the linked branch. The Channels page displays the channel to branch mapping if it exists.

Branches page location and contents

The Branches page is located at https://expo.dev/accounts/[account]/projects/[project]/branches. It displays a list of branches. Each branch detail page shows a list of updates with their runtime versions and platforms. A build and update are compatible when they share the same runtime version and platform. The most recent compatible update will be available for a build to download.

List all channels command

Use the command 'eas channel:list' to view all channels.

List all branches command

Use the command 'eas branch:list' to see all branches.

Rename branch preserves channel links

Renaming branches does not disconnect any channel-branch links. If a channel is linked to a branch and that branch is renamed, the channel remains linked to the now-renamed branch.

Rename branch command

Use the command 'eas branch:rename --from [branch-name] --to [branch-name]' to rename a branch. Example: 'eas branch:rename --from version-1.0 --to version-1.0-new'.

Edit channel to link to different branch

You can use the command 'eas channel:edit production --branch version-2.0' to change which branch a channel is linked to, allowing you to redirect a channel to a different branch after testing.

Publish an update command

To publish an update after making local changes, run eas update --channel [channel-name] --message [message]. For example, eas update --channel production --message "Fixes typo". Published updates are visible in the EAS dashboard at https://expo.dev/accounts/[account]/projects/[project]/updates.

Branch-based rollout definition

A branch-based rollout 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.

Per-update rollout definition

A per-update rollout 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.

Channel surfing use cases

Channel surfing can be used to: allow a single installed app to move between channels on demand without being tied to the build-time channel, enable preview and testing on real builds so developers and QA can try in-progress updates using the same production build that users have, and speed up iteration and validation by redirecting the app to another channel without waiting for a new build.

Channel surfing requires SDK 54 and expo-updates 0.29.0+

Channel surfing with Updates.setUpdateRequestHeadersOverride() is available in Expo SDK 54 with expo-updates version 0.29.0 and later.

Channel surfing compatibility rules

Channel surfing does not change native code or bypass update compatibility rules. The update on the selected channel must still match the installed app's platform and runtime version.

Prerequisites for channel surfing

To use channel surfing, you need: EAS Update configured, a release build installed (or debug build with EX_UPDATES_NATIVE_DEBUG enabled, not a development build with expo-dev-client), a channel configured at build time (the build must include expo-channel-name, which EAS Build adds from eas.json, or configure it with updates.requestHeaders in app.json or in native project), and a compatible update on the target channel for the installed app's platform and runtime version.

Updates.setUpdateRequestHeadersOverride() can only override embedded headers

Updates.setUpdateRequestHeadersOverride() can only override request header keys that were embedded in the build. For channel surfing, the build must include expo-channel-name. If you do not use EAS Build, configure the channel with updates.requestHeaders in app.json or in your native project.

Channel surfing overview and purpose

Channel surfing allows an installed release build to request updates from a different EAS Update channel at runtime. In the default EAS Update flow, the updates URL and channel are fixed at build time and set in the eas.json build profile. Channel surfing lets you override the expo-channel-name request header in JavaScript code so the app can request updates from a different channel without requiring a new build.

Channel surfing requires app-level trigger mechanism

Provide an app-level trigger for changing channels, such as a hidden menu for trusted users or another mechanism that fits your workflow. When a channel is selected, use Updates.setUpdateRequestHeadersOverride() to override the expo-channel-name request header.

Development builds do not support channel surfing

For developer-focused testing and to preview compatible updates, use a development build with expo-dev-client library instead. Channel surfing with Updates.setUpdateRequestHeadersOverride() is not supported in development builds. Most of the expo-updates API is unavailable in normal development builds.

Switch channels code example

import * as Updates from 'expo-updates'; export async function switchUpdateChannelAsync(channel: string) { Updates.setUpdateRequestHeadersOverride({ 'expo-channel-name': channel, }); const update = await Updates.checkForUpdateAsync(); if (update.isAvailable) { await Updates.fetchUpdateAsync(); } await Updates.reloadAsync(); }

Override persistence and behavior

Once set, the override persists on the device. After it is set, future update checks use the selected channel until the app clears or replaces the override, or until the app is uninstalled.

Clear channel override to return to build channel

Pass null to Updates.setUpdateRequestHeadersOverride() to clear the request header override and return to the channel configured in the build.

Clear channel override code example

import * as Updates from 'expo-updates'; export async function clearUpdateChannelOverrideAsync() { Updates.setUpdateRequestHeadersOverride(null); const update = await Updates.checkForUpdateAsync(); if (update.isAvailable) { await Updates.fetchUpdateAsync(); } await Updates.reloadAsync(); }

Updates.channel behavior with overrides

Updates.channel reflects the channel that was active when the app started. It does not update immediately after calling Updates.setUpdateRequestHeadersOverride(), but it reflects the new channel after the app reloads.

Update channels and rollouts feature

EAS Update supports rolling out changes to a percentage of users using rollouts functionality, allowing gradual deployment of updates to user bases.

When GitHub branches are deleted, EAS Update branches remain by default

When publishing updates to EAS Update branches named after GitHub branches (using `eas update --auto`, the `update` workflow job with `branch: ${{ github.ref_name }}`, or preview updates on every branch), deleting the GitHub branch leaves the EAS Update branch behind as an orphaned branch. A workflow using `ref_delete` and `branch-delete` can automate cleanup of these orphaned branches.

Give your agent this brain