Org Skills

Release engineering with EAS

Supporting material for react-native-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

Build profiles, update channels, runtime versions, rollback and store compliance. Open this when setting up releases, choosing a runtimeVersion policy, or answering "can we ship this as an update?".

Sources: https://docs.expo.dev/build/eas-json/ · https://docs.expo.dev/eas-update/getting-started/ · https://docs.expo.dev/eas-update/runtime-versions/ · https://expo.dev/changelog/sdk-55

1. The one rule everyone must know

EAS Update ships JavaScript and assets. Anything native needs a new build. Adding a library with native code, changing an app icon or splash, editing a config plugin, bumping the Expo SDK, changing permissions — all native. A JS-only bug fix, copy change or layout tweak — update.

Teach it as a question: did package.json gain a package with native code, or did app.json change? If yes, it is a build.

2. Build profiles

// eas.json
{
  "cli": { "version": ">= 12.0.0" },
  "build": {
    "development": { "developmentClient": true, "distribution": "internal", "channel": "development" },
    "preview": { "distribution": "internal", "channel": "preview" },
    "production": { "autoIncrement": true, "channel": "production" }
  },
  "submit": { "production": {} }
}
  • development builds the dev client that developers run against Metro.
  • preview is internal distribution for testers (TestFlight / internal track / direct install).
  • production is what goes to the stores, with autoIncrement handling buildNumber and versionCode so humans never edit them.

Channels map a build to an update branch, so a preview build can receive preview updates while production keeps its own stream.

3. Runtime versions

An update may only be delivered to a binary that can run it. The runtimeVersion expresses that compatibility.

// app.json
{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }
Policy Behaviour Pick it when
fingerprint Computed from everything affecting the native runtime; changes automatically when native code, plugins or the SDK change Default for CNG / managed projects — it makes an incompatible update extremely unlikely
appVersion Tied to version in app.json Only if a human reliably bumps version with every native change
nativeVersion Tied to version + build number Every build gets its own runtime; updates then reach a single build only
A literal string You control it by hand Bare projects with their own native release process

A wrong runtime version is the classic way to brick a release: the binary downloads an update it cannot execute. Verify with npx expo-updates fingerprint:generate before a production rollout when you are unsure.

4. Shipping and rolling back an update

eas update --branch production --message "fix: order total rounding"
eas update:rollback                  # interactive: revert users to the previous good update
eas update:list                      # inspect update groups and rollout state

A rollback republishes a known-good state rather than deleting the bad update, so devices that already downloaded the bad one are moved forward to the good one. Practise it once before you need it and keep the command in RELEASE.md.

Since SDK 55 updates are delivered as Hermes bytecode diffs, roughly a 75 % reduction in download size — which is another reason to keep runtimeVersion stable across a release series rather than churning it.

5. Staged rollout

  • Android: Play Console staged rollout percentage; iOS: phased release. Both on, always, for production.
  • EAS Update rolls out to a share of users: eas update --branch production --rollout-percentage=10, then eas update:edit to raise it, or eas update:revert-update-rollout to pull it back. Branch-level rollouts are driven by eas channel:rollout.
  • Define the abort condition before the rollout starts: "crash-free sessions below 99.5 % or error rate double the baseline → revert the rollout".

6. Release runbook (RELEASE.md)

1. Freeze: what is in the release (linked work items)
2. Verify: preview build tested on a low-end Android and the oldest supported iPhone
3. Version: bump `version` for a store release; builds auto-increment
4. Build: eas build --profile production --platform all
5. Submit: eas submit --profile production; note the review turnaround
6. Update: eas update --branch production --message "<change>" for JS-only fixes
7. Watch: crash-free sessions, error rate, key funnel, for 24 h
8. Roll back: eas update:rollback (JS) or submit the previous build (native)
Owner: <name> · Backup: <name>

7. Store compliance is part of the architecture

  • iOS privacy manifest (PrivacyInfo.xcprivacy): required, and must declare required-reason APIs and the data your app and its SDKs collect. Config plugins for third-party SDKs usually supply their own — verify rather than assume.
  • Play data safety form: must match what the app actually sends. It goes stale the moment an SDK is added; re-check it at every release.
  • Permissions: every usage string explains the user benefit; a generic string is a common rejection reason.
  • Android 16: edge-to-edge and predictive back are mandatory; test with gesture navigation on.
  • Account deletion: both stores require an in-app path if the app creates accounts.

8. CI shape

PR:    expo-doctor → tsc --noEmit → eslint → jest → eas build --profile preview (on label)
main:  the same → eas build --profile production → eas submit (manual approval)
JS fix: eas update --branch production (after the same checks)

EAS Workflows can express this in-repo; a GitHub Actions or Azure Pipelines job calling the same eas commands works equally well. What matters is that an update goes through the same checks as a build — a JS-only path that skips tests is how a bad update reaches everyone in minutes.