expo-release 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# expo-release
+
+Fingerprint-driven Expo releases: compare the current EAS fingerprint to **existing native builds**, then either publish an OTA or queue a native build (optionally auto-submitted to TestFlight or Play).
+
+This is not “last OTA on the channel vs current fingerprint.” A new runtime needs a matching native binary before installs can receive OTAs for that fingerprint.
+
+```
+Push / dispatch
+     │
+     ▼
+decide — git diff + eas fingerprint:generate + eas build:list
+     │
+     ├─ no matching impact paths → skip
+     ├─ finished native build with this fingerprint → eas update
+     ├─ matching native build in progress → OTA only
+     ├─ newest matching build errored → fail (use force-native after fixing)
+     └─ no matching native build → eas build --auto-submit --no-wait
+```
+
+## Install
+
+Use the composite action. The package is not published to npm.
+
+```yaml
+uses: HansKristoffer/expo-release@v2
+```
+
+The action runs `bun ${{ github.action_path }}/src/cli.ts`. The caller must already have checked out the repo (`fetch-depth: 0`), installed Bun, set up EAS, and installed workspace dependencies.
+
+Pin `eas-cli` with `expo/expo-github-action`. The CLI invokes `eas` from `PATH` (override with `EAS_BIN` for local tests), so that pin is the version that actually runs.
+
+## Setup checklist
+
+- [ ] GitHub secret `EXPO_TOKEN` from https://expo.dev/settings/access-tokens
+- [ ] `runtimeVersion: { policy: 'fingerprint' }` and `expo-updates` in the Expo app
+- [ ] `eas.json` channel on each profile you deploy (production, staging, …)
+- [ ] `eas.json` submit config when you use `--auto-submit`:
+  - iOS: `submit.<profile>.ios.ascAppId`
+  - Android: `submit.<profile>.android.serviceAccountKeyPath`
+- [ ] EAS credentials (`eas credentials` from the Expo app directory)
+- [ ] At least one finished native build **per profile and platform** on the current fingerprint. The first run against a new app always queues a native build.
+- [ ] `--environment` on every OTA for Expo SDK 55+
+- [ ] Add lockfiles (`bun.lock`, `package-lock.json`) to `impact-paths` if a dependency bump should trigger a fingerprint check. The default `apps/expo/` path does not include the workspace lockfile.
+
+## GitHub Action
+
+Copy this workflow into `.github/workflows/expo-release.yml`. Replace the marked consumer-specific bits.
+
+```yaml
+# =============================================================================
+# Expo Release
+# =============================================================================
+# Fingerprint decides OTA vs native store build. Push to main deploys production
+# when Expo paths change. Manual dispatch can force a native build or recover
+# an OTA.
+# =============================================================================
+
+name: Expo Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - apps/expo/**          # consumer: also list shared packages if needed
+      - bun.lock              # consumer: include if lockfile changes native deps
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: Recovery/deployment operation
+        required: true
+        default: deploy
+        type: choice
+        options:
+          - deploy
+          - force-native
+          - retry-ota
+          - republish
+          - rollback-embedded
+      group:
+        description: Update group ID (required for republish)
+        required: false
+        type: string
+      runtime-version:
+        description: Runtime version (optional for rollback-embedded)
+        required: false
+        type: string
+
+concurrency:
+  group: expo-release-production-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: production
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      # consumer: only if app.config.ts requires public URLs at eval time
+      EXPO_PUBLIC_API_URL: https://example.com
+      EXPO_PUBLIC_PLATFORM_URL: https://example.com
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22.12.0
+
+      - name: Restore Bun workspace cache
+        uses: actions/cache@v6
+        with:
+          path: |
+            node_modules
+            packages/*/node_modules
+            apps/*/node_modules
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Setup Expo and EAS
+        uses: expo/expo-github-action@v8
+        with:
+          eas-version: 16.32.0
+          token: ${{ secrets.EXPO_TOKEN }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Expo release
+        uses: HansKristoffer/expo-release@v2
+        with:
+          command: release
+          profile: production
+          operation: ${{ github.event.inputs.operation || 'deploy' }}
+          environment: production
+          impact-paths: apps/expo/
+          working-directory: apps/expo
+          group: ${{ github.event.inputs.group }}
+          runtime-version: ${{ github.event.inputs.runtime-version }}
+        env:
+          # Set variant keys on the action step (or the job). They must reach
+          # fingerprint:generate, build:list, eas build, and eas update.
+          APP_VARIANT: production
+          SECRETS_ENV: production
+          APS_ENVIRONMENT: production
+```
+
+A manual `deploy` from `workflow_dispatch` ignores the impact diff. That is intentional: dispatch after an unrelated commit should still release, not silently skip.
+
+### Action inputs
+
+| Input | Default | Notes |
+|-------|---------|--------|
+| `command` | `release` | `release` (decide + operate), `decide` (PR checks), or `operate` |
+| `profile` | `production` | EAS build profile; default update channel |
+| `operation` | `deploy` | See recovery operations below |
+| `deploy-type` | `none` | Used only when `command` is `operate` |
+| `base` / `head` | event before / `GITHUB_SHA` | Git range for the impact diff |
+| `impact-paths` | `apps/expo/` | Comma-separated repo-root prefixes |
+| `environment` | _(empty)_ | Passed to `eas update`. Required for Expo SDK 55+ |
+| `channel` | same as `profile` | EAS Update channel |
+| `platform` | `ios` | `ios` or `android`. Passed through to `eas update` and `eas build` |
+| `auto-submit` | `true` | Native builds use `--auto-submit` |
+| `working-directory` | `apps/expo` | Where `eas` runs |
+| `pre-update` | _(empty)_ | Shell command before `eas update` (OTA only) |
+| `post-update` | _(empty)_ | Shell command after a successful `eas update` (OTA only) |
+| `update-extra-args` | _(empty)_ | Extra tokens appended to `eas update` |
+| `group` | _(empty)_ | Required when `operation` is `republish` |
+| `runtime-version` | current fingerprint | Used when `operation` is `rollback-embedded` |
+| `message` | `{profile} {sha} (fp {hash})` | Override the generated `eas update` message |
+| `dry-run` | `false` | Print mutating EAS commands without executing them |
+
+### Action outputs
+
+| Output | Notes |
+|--------|--------|
+| `deploy_type` | Stable PR-check type: `none`, `ota`, `native` |
+| `native_build_pending` | `true` when a matching native build is still in progress |
+| `fingerprint` | Current EAS fingerprint hash |
+| `build_id` / `build_url` | Matching EAS build, if any |
+| `result` | Operate result (`skipped`, `ota`, `native-build`, `recovery`) |
+
+### PR checks (decide only)
+
+PR jobs should not operate. Use `command: decide` and comment or gate on `deploy_type`:
+
+```yaml
+- uses: HansKristoffer/expo-release@v2
+  id: decision
+  with:
+    command: decide
+    profile: pr-preview   # or production
+    base: ${{ steps.merge-base.outputs.sha }}
+    head: ${{ github.sha }}
+  env:
+    APP_VARIANT: staging
+    SECRETS_ENV: staging
+    APS_ENVIRONMENT: production
+```
+
+Then use `${{ steps.decision.outputs.deploy_type }}` (`none` / `ota` / `native`).
+
+The CLI writes the same JSON to stdout, including `deployType`:
+
+```bash
+bun "${{ github.action_path }}/src/cli.ts" decide \
+  --base "$BASE" --head "$HEAD" --profile production
+```
+
+`Bun.spawn` inherits process env. Set variant keys on the **action step or the job**, never on decide alone. When `app.config.ts` switches slug or bundle identifier on `APP_VARIANT`, every EAS command (`fingerprint:generate`, `build:list`, `eas build`, `eas update`) resolves a different project from that config.
+
+### OTA hooks
+
+`pre-update`, `post-update`, and `update-extra-args` run only on the OTA path (`deploy` + `ota`, and `retry-ota`). Skip, native builds, republish, and rollback ignore them. Hook commands inherit process env. A non-zero hook exit fails operate; `post-update` does not run if `eas update` fails.
+
+Production apps that export Hermes maps first set them only on the production operate step:
+
+```yaml
+- uses: HansKristoffer/expo-release@v2
+  with:
+    command: release
+    profile: production
+    environment: production
+    pre-update: bun scripts/release/export-hermes.ts
+    update-extra-args: --input-dir dist --skip-bundler
+    post-update: bunx posthog-cli hermes upload --directory dist
+  env:
+    APP_VARIANT: production
+    SECRETS_ENV: production
+    APS_ENVIRONMENT: production
+```
+
+`export-hermes.ts` is app-owned (typically `expo export --source-maps external` plus a Hermes `.map` check). Staging stays a default `eas update`.
+
+### Recovery operations
+
+| Operation | Effect |
+|-----------|--------|
+| `deploy` | Same as a push: decide, then OTA or native build |
+| `force-native` | Queue a native build (skip decide). Use this after fixing a failed fingerprint build. |
+| `retry-ota` | Publish an OTA even if the diff has no impact paths |
+| `republish` | `eas update:republish --group <id>`. Copy the group ID from the Expo dashboard. |
+| `rollback-embedded` | `eas update:roll-back-to-embedded` with `--runtime-version` (defaults to the current fingerprint) |
+
+### Dry run
+
+`--dry-run` still runs `git diff`, `eas fingerprint:generate`, and `eas build:list` so the decision is real. It only prints `eas update`, `eas build`, recovery commands, and OTA hooks.
+
+```yaml
+- uses: HansKristoffer/expo-release@v2
+  with:
+    command: release
+    profile: production
+    environment: production
+    dry-run: 'true'
+```
+
+## Multiple apps (staging and production)
+
+Use one job per profile, or a matrix. Each profile needs its own finished native build before OTAs work. One `EXPO_TOKEN` covers multiple projects under the same Expo account; separate accounts or orgs need separate secrets.
+
+Put the **profile in the concurrency group**. Two profiles deploying from the same ref should not serialize:
+
+```yaml
+concurrency:
+  group: expo-release-${{ matrix.profile }}-${{ github.ref }}
+  cancel-in-progress: false
+```
+
+### Two jobs, one branch each
+
+```yaml
+on:
+  push:
+    branches: [main, develop]
+
+jobs:
+  production:
+    if: github.ref == 'refs/heads/main'
+    # ... setup steps ...
+    steps:
+      - uses: HansKristoffer/expo-release@v2
+        with:
+          profile: production
+          environment: production
+          channel: production
+        env:
+          APP_VARIANT: production
+
+  staging:
+    if: github.ref == 'refs/heads/develop'
+    # ... setup steps ...
+    steps:
+      - uses: HansKristoffer/expo-release@v2
+        with:
+          profile: staging
+          environment: staging
+          channel: staging
+        env:
+          APP_VARIANT: staging
+```
+
+### One job, matrix
+
+```yaml
+strategy:
+  fail-fast: false
+  matrix:
+    include:
+      - profile: production
+        environment: production
+        variant: production
+      - profile: staging
+        environment: staging
+        variant: staging
+
+steps:
+  - uses: HansKristoffer/expo-release@v2
+    with:
+      profile: ${{ matrix.profile }}
+      environment: ${{ matrix.environment }}
+      channel: ${{ matrix.profile }}
+    env:
+      APP_VARIANT: ${{ matrix.variant }}
+```
+
+`channel` defaults to `profile`. If two profiles should publish to the same channel, set `channel` explicitly and keep `profile` as the EAS build profile.
+
+## CLI
+
+```bash
+expo-release release \
+  --base <sha> --head <sha> --profile production \
+  [--platform ios] \
+  [--impact-paths apps/expo/,packages/conductor/] \
+  [--environment production] \
+  [--dry-run]
+
+expo-release decide \
+  --base <sha> --head <sha> --profile production \
+  [--platform ios] \
+  [--impact-paths apps/expo/,packages/conductor/] \
+  [--ignore-expo-impact true]
+
+expo-release operate \
+  --profile production \
+  --deploy-type <none|ota|native> \
+  --operation <deploy|force-native|retry-ota|republish|rollback-embedded> \
+  [--channel production] [--environment production] \
+  [--platform ios] [--auto-submit true] \
+  [--group <update-group-id>] \
+  [--runtime-version <hash>] \
+  [--message "custom message"] \
+  [--pre-update "bun scripts/release/export-hermes.ts"] \
+  [--update-extra-args "--input-dir dist --skip-bundler"] \
+  [--post-update "bunx posthog-cli hermes upload --directory dist"]
+```
+
+`release` is decide + operate (same as the action default). `force-native`, `republish`, and `rollback-embedded` skip decide. `decide` prints JSON including `deployType` and `nativeBuildPending`. When `GITHUB_OUTPUT` is set, decide writes `deploy_type`, `native_build_pending`, `changed`, `fingerprint`, `build_id`, `build_url`. Operate writes `result`.
+
+```bash
+# local
+bun src/cli.ts decide --base HEAD^ --head HEAD --profile production
+```

package/action.yml

@@ -0,0 +1,162 @@
+name: Expo Release
+description: Fingerprint-driven EAS OTA or native store build
+author: Kristoffer Hansen
+
+inputs:
+  command:
+    description: release (decide + operate), decide only, or operate only
+    required: false
+    default: release
+  profile:
+    description: EAS build profile (also used as the default update channel)
+    required: false
+    default: production
+  operation:
+    description: deploy, force-native, retry-ota, republish, or rollback-embedded
+    required: false
+    default: deploy
+  deploy-type:
+    description: Decision type when command is operate (none, ota, native)
+    required: false
+    default: none
+  base:
+    description: Git base SHA for the impact diff. Defaults to github.event.before.
+    required: false
+    default: ''
+  head:
+    description: Git head SHA for the impact diff. Defaults to GITHUB_SHA.
+    required: false
+    default: ''
+  impact-paths:
+    description: Comma-separated repo-root paths that count as an Expo change
+    required: false
+    default: apps/expo/
+  environment:
+    description: EAS environment passed to eas update. Required for Expo SDK 55+.
+    required: false
+    default: ''
+  channel:
+    description: EAS Update channel. Defaults to the profile name.
+    required: false
+    default: ''
+  platform:
+    description: Native platform (ios or android)
+    required: false
+    default: ios
+  auto-submit:
+    description: Pass --auto-submit on native builds
+    required: false
+    default: 'true'
+  working-directory:
+    description: Directory to run EAS commands from
+    required: false
+    default: apps/expo
+  pre-update:
+    description: Shell command to run before eas update (OTA path only)
+    required: false
+    default: ''
+  post-update:
+    description: Shell command to run after a successful eas update (OTA path only)
+    required: false
+    default: ''
+  update-extra-args:
+    description: Extra tokens appended to eas update (e.g. --input-dir dist --skip-bundler)
+    required: false
+    default: ''
+  group:
+    description: Update group ID required by operation=republish
+    required: false
+    default: ''
+  runtime-version:
+    description: Runtime version for rollback-embedded. Defaults to the current fingerprint.
+    required: false
+    default: ''
+  message:
+    description: Override the generated eas update message
+    required: false
+    default: ''
+  dry-run:
+    description: Print mutating EAS commands without executing them
+    required: false
+    default: 'false'
+
+outputs:
+  deploy_type:
+    description: Stable PR-check type (none, ota, native)
+    value: ${{ steps.release.outputs.deploy_type }}
+  native_build_pending:
+    description: Whether a matching native build is still in progress
+    value: ${{ steps.release.outputs.native_build_pending }}
+  fingerprint:
+    description: Current EAS fingerprint hash
+    value: ${{ steps.release.outputs.fingerprint }}
+  build_id:
+    description: Matching EAS build id, if any
+    value: ${{ steps.release.outputs.build_id }}
+  build_url:
+    description: Matching EAS build URL, if any
+    value: ${{ steps.release.outputs.build_url }}
+  result:
+    description: Operate result (skipped, ota, native-build, recovery)
+    value: ${{ steps.release.outputs.result }}
+
+runs:
+  using: composite
+  steps:
+    - name: Expo release
+      id: release
+      working-directory: ${{ inputs.working-directory }}
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        EXPO_RELEASE_COMMAND: ${{ inputs.command }}
+        EXPO_RELEASE_PROFILE: ${{ inputs.profile }}
+        EXPO_RELEASE_OPERATION: ${{ inputs.operation }}
+        EXPO_RELEASE_DEPLOY_TYPE: ${{ inputs.deploy-type }}
+        EXPO_RELEASE_BASE: ${{ inputs.base }}
+        EXPO_RELEASE_HEAD: ${{ inputs.head }}
+        EXPO_RELEASE_IMPACT_PATHS: ${{ inputs.impact-paths }}
+        EXPO_RELEASE_ENVIRONMENT: ${{ inputs.environment }}
+        EXPO_RELEASE_CHANNEL: ${{ inputs.channel }}
+        EXPO_RELEASE_PLATFORM: ${{ inputs.platform }}
+        EXPO_RELEASE_AUTO_SUBMIT: ${{ inputs.auto-submit }}
+        EXPO_RELEASE_PRE_UPDATE: ${{ inputs.pre-update }}
+        EXPO_RELEASE_POST_UPDATE: ${{ inputs.post-update }}
+        EXPO_RELEASE_UPDATE_EXTRA_ARGS: ${{ inputs.update-extra-args }}
+        EXPO_RELEASE_GROUP: ${{ inputs.group }}
+        EXPO_RELEASE_RUNTIME_VERSION: ${{ inputs.runtime-version }}
+        EXPO_RELEASE_MESSAGE: ${{ inputs.message }}
+        EXPO_RELEASE_DRY_RUN: ${{ inputs.dry-run }}
+        GITHUB_EVENT_BEFORE: ${{ github.event.before }}
+      run: bun "$ACTION_PATH/src/cli.ts"
+
+    - name: Publish job summary
+      if: always()
+      shell: bash
+      env:
+        COMMAND: ${{ inputs.command }}
+        OPERATION: ${{ inputs.operation }}
+        PROFILE: ${{ inputs.profile }}
+        PLATFORM: ${{ inputs.platform }}
+        DEPLOY_TYPE: ${{ steps.release.outputs.deploy_type }}
+        RESULT: ${{ steps.release.outputs.result || 'did not run' }}
+        FINGERPRINT: ${{ steps.release.outputs.fingerprint }}
+        MATCHING_BUILD: ${{ steps.release.outputs.build_url || steps.release.outputs.build_id }}
+        NATIVE_PENDING: ${{ steps.release.outputs.native_build_pending }}
+      run: |
+        {
+          echo "## ${PROFILE} ${PLATFORM} ${COMMAND}"
+          echo ""
+          echo "- Command: \`$COMMAND\`"
+          echo "- Operation: \`$OPERATION\`"
+          echo "- Result: \`$RESULT\`"
+          if [[ -n "$DEPLOY_TYPE" ]]; then
+            echo "- Deploy type: \`$DEPLOY_TYPE\`"
+            echo "- Native build pending: \`${NATIVE_PENDING:-false}\`"
+            echo "- Fingerprint: \`${FINGERPRINT:-none}\`"
+            echo "- Matching build: ${MATCHING_BUILD:-none}"
+          fi
+          if [[ "$COMMAND" == "release" ]]; then
+            echo "- New native builds are submitted automatically when auto-submit is enabled (TestFlight on iOS, Play on Android)."
+          fi
+        } >> "$GITHUB_STEP_SUMMARY"

package/dist/args.d.ts

@@ -0,0 +1,38 @@
+export declare const DEFAULT_IMPACT_PATHS: readonly ['apps/expo/'];
+export type ReleasePlatform = 'ios' | 'android';
+export type CommandName = 'release' | 'decide' | 'operate';
+export type Operation = 'deploy' | 'force-native' | 'retry-ota' | 'republish' | 'rollback-embedded';
+export type DeployType = 'none' | 'ota' | 'native';
+export type ReleaseOptions = {
+    command: CommandName;
+    profile: string;
+    base?: string;
+    head?: string;
+    platform: ReleasePlatform;
+    impactPaths: string[];
+    ignoreExpoImpact: boolean;
+    operation: Operation;
+    deployType: DeployType;
+    channel: string;
+    environment?: string;
+    autoSubmit: boolean;
+    preUpdate?: string;
+    postUpdate?: string;
+    updateExtraArgs?: string;
+    group?: string;
+    runtimeVersion?: string;
+    message?: string;
+    fingerprint?: string;
+    dryRun: boolean;
+};
+export declare const USAGE = "Usage: expo-release <release|decide|operate> --profile <profile> [--base <sha>] [--head <sha>] [--platform ios|android] [--impact-paths apps/expo/] [--operation deploy|force-native|retry-ota|republish|rollback-embedded] [--deploy-type none|ota|native] [--channel <channel>] [--environment <env>] [--group <id>] [--runtime-version <hash>] [--message <msg>] [--fingerprint <hash>] [--auto-submit true] [--pre-update <cmd>] [--post-update <cmd>] [--update-extra-args <args>] [--dry-run] [--ignore-expo-impact true]";
+export declare function optionalString(value: string | undefined): string | undefined;
+export declare function parseImpactPaths(value: string | undefined): string[];
+export declare function parsePlatform(value: string | undefined): ReleasePlatform;
+export declare function parseBoolean(value: string | undefined, fallback: boolean): boolean;
+export declare function parseOperation(value: string | undefined): Operation;
+export declare function parseDeployType(value: string | undefined): DeployType;
+export declare function parseCommandName(value: string | undefined): CommandName;
+export declare function needsDecide(operation: Operation): boolean;
+export declare function shouldIgnoreExpoImpact(options: Pick<ReleaseOptions, 'ignoreExpoImpact' | 'operation'>): boolean;
+export declare function parseReleaseOptions(args: string[], env?: NodeJS.ProcessEnv): ReleaseOptions;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};