Set correct APP_VARIANT for EAS Update commands
When publishing JavaScript updates via EAS Update, set the correct APP_VARIANT environment variable when running eas update command to ensure updates apply to the correct app variant.
update channels & rollouts
184 notes in this subject, read out of this brain and free to use. This is page 1 of 4.
expo-updates integration
EAS Build has first-class support for the expo-updates library with per-profile channels and runtime version guidance, allowing you to coordinate updates pushed via EAS Update with app store releases.
Runtime version and binary compatibility with EAS Update
The native runtime may change on each build if native code is modified in a way that changes the API contract with JavaScript. Publishing a JavaScript bundle to a binary with an incompatible native runtime may cause the app to not work as expected or crash. Use a different runtime version for each binary version of the app. Any time the native runtime changes (such as when adding or removing a native library, or modifying app.json in CNG projects), increment the runtime version.
runtimeVersion updates cannot be loaded in Expo Go
Updates published with the runtimeVersion field cannot be loaded in Expo Go. Instead, use expo-dev-client to create a development build for previewing updates.
Coordinate updates with build profiles using channels
Use different channels in eas.json for different build profiles to coordinate which updates are pulled by each built version. For example, production builds can pull from the production channel while preview/staging builds pull from a staging channel.
eas/configure_eas_update requirement
To use the eas/configure_eas_update function you need to have EAS Update configured for your project.
eas/configure_eas_update function
The eas/configure_eas_update function configures runtime version and release channel for your build. It has the following properties: name (optional, defaults to 'Configure EAS Update'), inputs.runtime_version (optional, string, defaults to ${ eas.job.version.runtimeVersion } or natively defined runtime version), inputs.channel (optional, string, defaults to ${ eas.job.updates.channel }).
Update verification continues after certificate expiration
Updates downloaded before the expiration of their signing certificate will continue to function normally. Only updates downloaded after certificate expiration will fail verification.
XML escape certificate for Android command
Use the command: node -e "console.log(require('fs').readFileSync('./certs/certificate.pem', 'utf8').replace(/\\r/g, '
').replace(/\\n/g, '
'));" to generate an XML-escaped version of the certificate for Android manifest configuration.
Generate private key and certificate command
Use the command: npx expo-updates codesigning:generate --key-output-directory ../keys --certificate-output-directory certs --certificate-validity-duration-years 10 --certificate-common-name "Your Organization Name". This generates: ../keys/private-key.pem (private key), ../keys/public-key.pem (public key), and certs/certificate.pem (code signing certificate). The key-output-directory should be outside of source control to prevent accidentally checking in the private key.
XML escape certificate for iOS command
Use the command: node -e "console.log(require('fs').readFileSync('./certs/certificate.pem', 'utf8').replace(/\\r/g, '
'));" to generate an XML-escaped version of the certificate for iOS plist configuration.
Code signing configuration with CNG
If using Continuous Native Generation (CNG) to generate native projects, the app.json configuration generated by npx expo-updates codesigning:configure command is all that is needed. The changes will be applied to the native projects the next time they are generated.
Code signing overview and purpose
The expo-updates library supports end-to-end code signing using public-key cryptography. Code signing allows developers to cryptographically sign their updates with their own keys. The signatures are verified on the client before the update is applied, which ensures ISPs, CDNs, cloud providers, and even EAS itself cannot tamper with updates run by apps.
Code signing configuration for Android without CNG
If not using CNG, add two meta-data fields to the <application> element in android/app/src/main/AndroidManifest.xml: expo.modules.updates.CODE_SIGNING_CERTIFICATE (with XML-escaped certificate as value) and expo.modules.updates.CODE_SIGNING_METADATA with value {"keyid":"main","alg":"rsa-v1_5-sha256"}. The certificate must be XML-escaped by replacing \r with 
 and \n with 
.
Private key storage requirements
The generated private key must be kept private and secure. Store the private key in a directory outside of source control to ensure it is not accidentally checked in. Store the private key the same way you would store other sensitive information, such as in a KMS or password manager.
EAS Update Code Signing availability
EAS Update Code Signing is only available to accounts subscribed to the EAS Production or Enterprise plans. See EAS pricing plans for details.
Certificate validity duration considerations
Certificate validity duration varies based on security needs. A shorter validity duration requires more frequent key rotation but is considered better practice since a compromised private key has sooner expiration, limiting exposure. Shorter validity durations add overhead to the app's release process as the key must be rotated more frequently. Binaries with expired certificates will not apply new updates. Expo sets this value to 20 years for the public Expo Go app but only 1 year for internal apps with binaries distributed more frequently. Expo plans to rotate keys every 10 years.
Key rotation reasons
Key rotation is the process of changing the key pair used for signing updates. Common reasons include: key expiration (after the certificate validity period elapses, updates signed with that key will no longer be applied); private key compromise (if the private key is exposed publicly, the integrity of updates can no longer be guaranteed); and security best practices (rotating keys periodically ensures system resilience).
Configure code signing command
Use the command: npx expo-updates codesigning:configure --certificate-input-directory certs --key-input-directory ../keys. This configures your project to use code signing.
Key rotation procedure
To rotate keys: (1) Back up the old keys and certificate that were generated initially. (2) Generate a new key by following the generation steps from the beginning. Optionally change the keyid of the new key by modifying updates.codeSigningMetadata.keyid in app.json. (3) Set a new runtime version for builds using this certificate to ensure only updates signed with the new key run in the new build. (4) Publish signed updates using the new key.
Certificate storage and inclusion
The certificate should be included in the project and checked into source control. It contains the public key and a method for verifying code signatures. When a signed update is downloaded, the update's signature is verified using this certificate.
Removing code signing process
To remove code signing from an app, treat it as a key rotation to a null key: (1) Back up the old key and certificate. (2) Remove the updates.codeSigningMetadata field from your app config (app.json). (3) Set a new runtime version for builds to ensure only unsigned updates run in the new build.
Public key storage
The public key may be stored alongside the private key. It is not sensitive information.
Build with new runtime version after code signing configuration
After configuring code signing, create a new build with a new runtime version. The code signing certificate will be embedded in this new build.
Code signing configuration for iOS without CNG
If not using CNG, add two key-value pairs to the <dict> element in ios/project-name/Supporting/Expo.plist: EXUpdatesCodeSigningCertificate (with XML-escaped certificate as string value) and EXUpdatesCodeSigningMetadata (with nested dict containing keyid "main" and alg "rsa-v1_5-sha256"). The certificate must be XML-escaped by replacing \r with 
 but leaving \n unescaped.
Update verification on client
When downloading an update on the client, the build configured for code signing checks if there is a new update available. The server responds with the update and its generated signature. After being downloaded but before being applied, the update is verified against the embedded certificate and included signature. The update is applied if the certificate and signature are valid, and rejected otherwise.
Publish signed update command
Use the command: eas update --private-key-path ../keys/private-key.pem to publish a signed update for your app.
EAS Update code signing process
During an EAS Update publish using eas update, the EAS CLI automatically detects that code signing is configured. It verifies the integrity of the update and creates a digital signature using your private key. This process is performed locally so that your private key never leaves your machine. The generated signature is automatically sent to EAS to store alongside the update.
Rollback updates with EAS Update
You can roll back updates in EAS Update using the 'eas update:rollback' command.
Channel surfing for non-technical testing
Channel surfing allows switching update channels in non-development builds at runtime. This enables non-technical stakeholders to test features from a single build on Google Play Beta and TestFlight, similar to CodePush's deployment switching. Development builds can also load updates from any compatible channel.
EAS Update fingerprint and runtimeVersion
Each update and build created with EAS is associated with a fingerprint. You can diff fingerprints through the website UI or with 'eas fingerprint:compare' to see what changed in the native runtime between builds and updates, understand build/update compatibility, and guide decisions about bumping the runtimeVersion.
End-to-end code signing with EAS Update
EAS Update supports end-to-end code signing, available for EAS Production and Enterprise plan subscribers.
Direct control over update download and application
EAS Update allows direct control over when an update is downloaded and applied through different strategies, such as checking for updates while the app is running or when backgrounded using Updates.checkForUpdateAsync().
Gradual rollouts with EAS Update
EAS Update supports various strategies for gradually rolling out updates. See the rollouts guide for different approaches.
Handle different environments with EAS Update channels and branches
EAS Update supports managing different environments such as staging and production using channels and branches. This is managed through EAS CLI.
Override update configuration at runtime with EAS Update
You can switch the target update stream at runtime in EAS Update using Updates.setUpdateURLAndRequestHeadersOverride(), similar to CodePush's sync() function.
Update messages in EAS Update
EAS Update does not have a --description flag like CodePush. Instead, you can include a message in an update using the extra field in your app config.
Mandatory updates with EAS Update
EAS Update does not have a specific flag for mandatory updates like CodePush's --mandatory flag. You can build mandatory/critical update functionality with EAS Update using custom implementation. See the critical/mandatory updates documentation for more details.
EAS Update vs CodePush - runtime update selection control
With CodePush, the client controls the target update deployment at runtime. With EAS Update, the default path is server-side controlled by mapping channels to branches. A build requests updates for its configured channel, and EAS Update returns the latest compatible update from the mapped branch. Channel surfing allows switching update channels in non-development builds at runtime, similar to CodePush's runtime deployment control.
EAS Update vs CodePush - streams organization
CodePush uses single streams of updates for deployments and allows changing the deployment at runtime through JavaScript API. EAS Update uses multiple streams: branches (corresponding to source control branches) and channels (which point to branches). Channels are mapped to branches server-side and can point to different branches for each runtime version. Builds point to channels, not directly to branches.
Recommended staging build practice with EAS Build
A common practice for creating staging builds is to always create one whenever you upload a production build to a store. This allows you to have a staging build with an identical runtime to the production build, which you can use to test updates before rolling them out to production. With EAS Build, this means running `eas build --profile staging --auto-submit` every time you run `eas build --profile production --auto-submit`.
Multiple binary versions in production and targeting with EAS Update
When you have an app with multiple binary versions in production, EAS Update's channels, branches, and runtime versions help you determine which app version to target, provide bookkeeping to understand deployment state, and support targeting a particular version with a hotfix.
Preview builds point to preview channel
Preview builds will point to the "preview" channel. If you want multiple versions of the preview app distributed internally at any given time, you can change the channel name based on the feature name, such as "preview-feature-a" or "preview-feature-b".
Per-update rollouts for gradual deployment
Per-update rollouts allow deploying updates gradually to an increasing percentage of users. Use `eas update --rollout-percentage 10` to roll out an update to 10% of users. Use `eas update:edit` to edit the rollout percentage later.
Incrementing app version for new production builds
When creating a new production build, increment the app version to ensure it has a unique runtime version for each release of the app.
Promoting updates from staging to production
If you have already published a fix to staging and verified it there, ensure you republish from the same commit. If identical environment variables and code signing configuration are used on staging and production, you can run `eas update:republish --destination-channel production` to promote the update rather than generating a new one. This ensures the exact same bundle tested in staging is used in production.
Publishing update to production
Run `eas update --channel production` to bundle and push a new update to production. This makes the hotfix immediately available to production build users with the same runtime version.
Publishing update to staging
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 environment is typically Google Play Beta or TestFlight on respective app stores.
What channels indicate
Channels indicate which environment an update targets, such as "production" or "staging". Runtime versions indicate the app version that the update will target, such as "1.0.0" or "1.0.1".
Rolling back to a previous update
If you have mistakenly published an update to any environment, run `eas update:rollback` to initiate a rollback to a previous update.
Simplified release process using channels and runtime versions
A simple but powerful release process uses channels and runtime versions while mostly ignoring branches. This gives most of the benefits of EAS Update with minimal conceptual overhead. Channels are kept pointed at a branch with the same name as the channel.
Branch promotion flow: version-based channels with manual runtime versions
The branch promotion flow manages versioned releases using version-based branches like 'version-1.0' that are dynamically mapped to channels to promote tested changes from testing to production. It requires creating separate builds for production (one per major version) and testing, testing on TestFlight and Play Store Internal Track and/or internal distribution builds, and creating version-based update branches. This flow does not support automatic runtime version policies (sdkVersion, appVersion, nativeVersion, or fingerprint) and requires manually specifying runtime versions.
Platform-specific flow advantages and disadvantages
Advantages of platform-specific flow: full control over which updates go to Android and iOS builds, ensuring updates never apply to both platforms simultaneously. Disadvantages: must run two commands instead of one to fix changes on both platforms.
Branch promotion flow workflow
The branch promotion flow workflow is: develop locally and test in Expo Go or development build, create builds with channels named 'production-rtv-1' (indicating runtime version '1') for app stores and 'staging' for testing, set up expo-github-action to publish updates on branch merges, merge changes into 'version-1' branch, use website or EAS CLI to point 'staging' channel at 'version-1' branch and test, then point 'production-rtv-1' channel at 'version-1' to deploy. For new releases without new runtime versions, create 'version-2' branch and point channels accordingly. For new releases requiring new runtime versions, bump runtime version, create new staging build with new runtime version, create new 'version-2' branch, create new 'production-rtv-2' build, and point channels accordingly.
Persistent staging flow advantages and disadvantages
Advantages of persistent staging flow: control the pace of production deployment independently from development pace, adding extra testing opportunities and avoiding users downloading updates after every PR merge, and easy team communication since deployments happen on GitHub branches named 'staging' and 'production'. Disadvantages: checking out previous app versions is more complex (requires checking out old commits rather than old branches), and when merging to 'production', the update is rebuilt and republished instead of being moved from 'staging' builds.
Persistent staging flow: environment-based branches
The persistent staging flow uses un-versioned persistent 'staging' and 'production' branches that can be merged into forever. It creates separate builds for production and testing, tests changes on TestFlight and Play Store Internal Track and/or internal distribution builds, and publishes updates to environment-based branches. The workflow is: develop locally and test in Expo Go, create 'production' builds for app store review and 'staging' builds for testing, set up expo-github-action to publish updates on branch merges, merge into 'staging' branch to publish to test builds, then merge into 'production' branch to publish to production builds.
Two-command flow advantages and disadvantages
Advantages of the two-command flow: no bookkeeping of extra version or environment names (easy communication), and very fast update delivery. Disadvantages: no pre-production checks to verify code functionality, relying only on testing with Expo Go or a development build rather than a dedicated test environment.
Two-command flow: simplest EAS Update deployment pattern
The two-command flow is the simplest and fastest deployment pattern with the fewest safety checks, suitable for trying out Expo and smaller projects. It uses production-only builds, tests changes in Expo Go or development builds, and publishes updates to a single branch. The workflow is: develop locally and test in a development build or Expo Go, run `eas build` to create builds and submit them to app stores, then run `eas update --branch production` to deliver updates to users immediately.
Platform-specific flow: separate Android and iOS update channels
The platform-specific flow builds and updates Android and iOS apps separately, requiring separate commands for delivering updates to each platform. It uses environment- and platform-based branches like 'ios-staging', 'ios-production', 'android-staging', and 'android-production'. The workflow is: develop locally and test in Expo Go, create builds with platform-specific channel names, put staging builds on TestFlight and Play Store Internal Track, submit production builds to app stores, set up expo-github-action to publish platform-specific updates, then merge iOS changes into ios-staging/ios-production branches and Android changes into android-staging/android-production branches.
Branch promotion flow advantages and disadvantages
Advantages of branch promotion flow: safer than other flows with all updates tested on test builds before deployment, exact tested artifact is deployed to production, direct mapping between GitHub branches and EAS Update branches creates mapping between GitHub commits and EAS Update updates, and previous deployments are always preserved on GitHub for easy version checkout. Disadvantages: requires one channel per production runtime version for historical updates (making runtime version policies difficult), requires bookkeeping of branch names and team communication about which branches point to test and production builds.