# Release engineering with EAS

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

```json
// 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.

```json
// 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

```bash
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.
