Skip to content

feat(expo): release, promote, patch and roll back Expo Updates apps #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ciehanski merged 1 commit into from
Sep 29, 2026
Merged

feat(expo): release, promote, patch and roll back Expo Updates apps #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 78 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ Before upgrading a CI pipeline to 1.2.0, note two changes: an unknown flag is no
- [Releasing Updates](#releasing-updates)
- [Releasing Updates (General)](#releasing-updates-general)
- [Releasing Updates (React Native)](#releasing-updates-react-native)
- [Releasing Updates (Expo Updates)](#releasing-updates-expo-updates)
- [Debugging DeployPulse Integration](#debugging-deploypulse-integration)
- [Patching Update Metadata](#patching-update-metadata)
- [Promoting Updates](#promoting-updates)
Expand Down Expand Up @@ -157,6 +158,15 @@ dpctl app add MyApp-iOS

_NOTE: Using the same app for iOS and Android may cause installation exceptions because the DeployPulse update package produced for iOS will have different content from the update produced for Android._

You can also record what kind of app it is with `--platform`: `ios`, `android`, `expo-cng-ios`, `expo-cng-android` or `expo-v1`. The platform can't be changed after the app is created. dpctl uses it to stop you running `release-react` on an Expo Updates app, or `release-expo` on a CodePush app.

```
dpctl app add MyApp-iOS --platform ios
dpctl app add MyExpoApp --platform expo-v1
```

Apps that use `expo-updates` must be created with `--platform expo-v1`, since that is the only type the Expo Updates release endpoint accepts. They are also the exception to one app per platform: a single `expo-v1` app serves both, and `dpctl release-expo` releases iOS and Android to it separately.

All new apps automatically come with two deployments (`Staging` and `Production`) so that you can begin distributing updates to multiple channels without needing to do anything extra (see deployment instructions below). After you create an app, the CLI will output the deployment keys for the `Staging` and `Production` deployments, which you can begin using to configure your mobile clients with the [React Native](http://github.com/deploypulseio/react-native-code-push) SDK.

If you decide that you don't like the name you gave to an app, you can rename it at any time using the following command:
Expand All @@ -182,6 +192,8 @@ you can run the following command:
dpctl app ls
```

The list shows each app's platform, which tells you whether to release it with `dpctl release-react` or `dpctl release-expo`.

### Code Signing - Set Public Key

To enable bundle integrity verification on an app, upload your RSA public key using the following command:
Expand Down Expand Up @@ -311,13 +323,15 @@ When the metrics cell reports `No installs recorded`, that indicates that the se

## Releasing Updates

Once your app has been configured to query for updates against the DeployPulse API, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the dpctl CLI includes two different commands for releasing updates:
Once your app has been configured to query for updates against the DeployPulse API, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the dpctl CLI includes three different commands for releasing updates:

1. [General](#releasing-updates-general) - Releases an update to the DeployPulse API that was generated by an external tool or build script (e.g. a Gulp task, the `react-native bundle` command). This provides the most flexibility in terms of fitting into existing workflows, since it strictly deals with CodePush-specific step, and leaves the app-specific compilation process to you.

2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the task of generating the updated app contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `dpctl release`.

Which of these commands you should use is mostly a matter of requirements and/or preference. However, we generally recommend using the platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose `release` command if/when greater control is needed.
3. [Expo Updates](#releasing-updates-expo-updates) - For apps that use `expo-updates` instead of the CodePush SDK. Exports your project with `npx expo export` and releases iOS and Android in one command.

Expo Updates apps always use `release-expo`. For CodePush apps, which of the other two commands you use is mostly a matter of requirements and/or preference. However, we generally recommend using the platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose `release` command if/when greater control is needed.

### Releasing Updates (General)

Expand Down Expand Up @@ -491,6 +505,8 @@ The `release-react` command is a React Native-specific version of the "vanilla"

3. Compiling the bundle to Hermes bytecode when Hermes is enabled for the platform (see the [Hermes parameters](#hermes-parameters)).

If the app is an Expo Updates app, `release-react` stops before bundling and tells you to use [`release-expo`](#releasing-updates-expo-updates) instead.

To illustrate the difference that the `release-react` command can make, the following is an example of how you might generate and release an update for a React Native app using the "vanilla" `release` command:

```shell
Expand Down Expand Up @@ -666,6 +682,39 @@ It does what `eas update` does before uploading:

Both platforms are exported and packaged before either is uploaded, so a problem with one can't leave the other released on its own. If you run `release-expo` on a CodePush app, dpctl stops before exporting and tells you to use `release-react` instead.

#### Deployment name parameter

This is the same parameter as the one described in the [above section](#deployment-name-parameter).

#### Platform parameter

`ios` or `android` releases only that platform. If left unspecified, both are released.

_NOTE: This parameter can be set using either --platform or -p_

#### Runtime version parameter

The runtime version the update targets. If left unspecified, it is resolved for each platform from your app config. Pass it when you aren't running dpctl from the project folder. With the `fingerprint` policy iOS and Android usually have different runtime versions, so in that case release each platform separately with its own value.

_NOTE: This parameter can be set using either --runtimeVersion or -r_

#### Export directory parameter

The folder written by an earlier `npx expo export`, to release instead of exporting again, for example from a previous CI step. dpctl never deletes it.

```shell
npx expo export --output-dir dist
dpctl release-expo MyExpoApp -d Production --exportDir dist
```

#### Metadata parameter

Extra metadata to attach to the release, as a JSON string. It is included in the manifest that devices receive.

```shell
dpctl release-expo MyExpoApp --metadata '{"channel":"beta"}'
```

## Debugging DeployPulse Integration

Once you've released an update, React Native plugin has been integrated into your app, it can be helpful to diagnose how the plugin is behaving, especially if you run into an issue and want to understand why. In order to debug the DeployPulse update discovery experience, you can run the following command in order to easily view the diagnostic logs produced by the CodePush plugin within your app:
Expand Down Expand Up @@ -841,6 +890,33 @@ dpctl rollback MyApp-iOS Production --targetRelease v34

_NOTE: The release produced by a rollback will be annotated in the output of the `deployment history` command to help identify them more easily._

### Rolling back an Expo Updates app

On an app created with `--platform expo-v1`, `rollback` works on a channel rather than a deployment, and
releases have no labels, so `--targetRelease` does not apply:

```
dpctl rollback MyExpoApp production
```

A channel serves one release per platform **and** runtime version, so this rolls back each of them. Narrow it
with `--platform ios|android` or `--runtimeVersion 1.2.0`.

The previous release is published again as a new release. That is what actually moves devices: `expo-updates`
only loads an update newer than the one it launched, so taking the bad release out of service on its own
would strand every device that already downloaded it. The rolled back release is disabled at the same time,
which also clears any partial rollout it had, so the channel is free to take a new release.

When a channel has no earlier release, or every release on it is bad, send devices back to the bundle built
into the store binary instead:

```
dpctl rollback MyExpoApp production --toEmbedded
```

That issues the Expo `rollBackToEmbedded` directive. Devices return to the bundle they shipped with until the
channel gets a new release, which supersedes the rollback.

## Auto-Rollback

Auto-rollback automatically reverts a deployment to its previous release when the error rate on the current release exceeds a configured threshold. This protects your users from bad releases without requiring manual intervention.
Expand Down
Loading
Loading