/mobile-deployment-eas

name: mobile-deployment-eas
description: EAS Build, Update, Submit deployment patterns

EAS Deployment Patterns

> **Quick Guide:** EAS (Expo Application Services) handles cloud builds, OTA updates, and app store submission. Use build profiles in `eas.json` to separate development/preview/production builds. Use EAS Update with runtime version fingerprinting for safe OTA deploys. Use `--environment` flag (SDK 55+) instead of `--channel` when publishing updates. Let EAS manage credentials unless you have enterprise requirements.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use the `--environment` flag with `eas update` on SDK 55+ projects -- the `--channel` flag is replaced)**

**(You MUST set `runtimeVersion` with `"fingerprint"` policy for projects with native dependencies -- mismatched runtime versions crash apps on OTA update)**

**(You MUST use EAS Secrets for sensitive values -- NEVER put API keys or tokens in `eas.json` env blocks or `EXPO_PUBLIC_` variables)**

**(You MUST run `eas build` from the app directory in monorepos -- NOT from the repository root)**

</critical_requirements>

---

**Auto-detection:** EAS Build, EAS Update, EAS Submit, eas.json, eas build, eas update, eas submit, eas credentials, eas secret, EAS Workflows, build profiles, OTA updates, runtime version, fingerprint policy, app store submission, code signing, eas-cli

**When to use:**

• Configuring cloud builds for iOS and Android
• Publishing OTA (over-the-air) updates to deployed apps
• Submitting builds to App Store or Google Play
• Managing iOS provisioning profiles and Android keystores
• Setting up CI/CD pipelines for mobile deployment
• Configuring build profiles for different environments

**Key patterns covered:**

• `eas.json` build profiles with inheritance (`extends`)
• EAS Update channels, branches, and runtime versions
• EAS Submit for iOS App Store and Google Play
• Credentials management (automatic vs local)
• EAS Secrets for sensitive build-time values
• EAS Workflows for CI/CD automation
• Monorepo build configuration
• Version management with `autoIncrement` and `appVersionSource`

**When NOT to use:**

• General Expo SDK development (app.config.ts, Expo Router, components)
• Local-only builds with `npx expo run:ios/android` without EAS
• Projects not using Expo managed workflow

---

<philosophy>

Philosophy

EAS separates **building**, **updating**, and **submitting** into distinct services that compose into a deployment pipeline. The key insight is that most mobile deployment complexity lives in credentials, versioning, and environment management -- EAS automates all three.

**Core principles:**

1. **Profiles over flags** -- Define build configurations in `eas.json`, not as CLI arguments scattered across scripts 2. **Channels isolate environments** -- Production, preview, and development builds receive only their intended updates 3. **Fingerprint prevents crashes** -- Runtime version fingerprinting auto-detects native changes so OTA updates never land on incompatible builds 4. **Credentials are managed** -- Let EAS handle signing unless you have enterprise requirements; it generates, stores, and renews certificates automatically 5. **Secrets stay server-side** -- Sensitive values live in EAS Secrets, never in config files or client-side variables

**Mental model:**

`eas.json` is your deployment configuration hub. Build profiles define HOW to build (development client, APK vs AAB, simulator vs device). Channels define WHERE updates go. Runtime versions define WHAT is compatible. Secrets define access to external services during builds.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Build Profiles with Inheritance

Use `extends` to share configuration between profiles. Define a `base` profile for shared settings, then extend for each environment.

{
  "build": {
    "base": {
      "node": "20.17.0",
      "env": { "EXPO_PUBLIC_APP_ENV": "development" }
    },
    "development": {
      "extends": "base",
      "developmentClient": true,
      "distribution": "internal",
      "ios": { "simulator": true },
      "android": { "buildType": "apk" }
    },
    "production": {
      "extends": "base",
      "autoIncrement": "buildNumber",
      "channel": "production",
      "env": { "EXPO_PUBLIC_APP_ENV": "production" }
    }
  }
}

**Why good:** `extends` eliminates duplication across profiles, `autoIncrement` handles version bumps automatically, environment-specific env vars prevent mixing configurations

> Full profile examples with all options: [examples/core.md](examples/core.md) - Build Profiles section

---

Pattern 2: Runtime Versions and Fingerprinting

Runtime version determines which builds are compatible with which OTA updates. The `"fingerprint"` policy auto-detects native changes.

// app.config.ts
export default {
  runtimeVersion: {
    policy: "fingerprint", // Auto-detects native code changes
  },
  updates: {
    url: `https://u.expo.dev/${process.env.EAS_PROJECT_ID}`,
  },
};

| Policy | Behavior | Best For | | ------------- | ------------------------------ | -------------------------------- | | `fingerprint` | Hashes all native dependencies | Complex apps with native modules | | `appVersion` | Uses `version` from app config | Simple apps, manual control | | Custom string | Exact match (e.g., `"1.0.0"`) | Full manual control |

**Gotcha:** `fingerprint` can be aggressive -- it may flag changes that don't actually affect native code, requiring more builds than necessary. Use `appVersion` for simpler projects.

> Full configuration examples: [examples/core.md](examples/core.md) - Runtime Versions section

---

Pattern 3: Publishing OTA Updates

Updates go to a ch