ci(test-app): key the fixture build cache on the Expo fingerprint

The fixture cache key was a hand-maintained `hashFiles` list, and it already
had a hole: `accessory-setup.config.json` was absent from it, but app.config.js
reads that file into `NSAccessorySetupBluetoothServices`. Editing the service
UUID changed the Info.plist without changing the key, so the cache would serve
an app built from the old value. The Expo fingerprint enumerates the native
inputs instead of us restating them, and covers that file as a config-plugin
source. @expo/fingerprint ships a CLI that prints it; passing no --platform is
deliberate, since its default is what @expo/cli hashes for its own build cache,
so the key agrees with what `expo run:*` looks up.

The fingerprint hashes the native build and nothing else — it exists to decide
native/JS compatibility, so the bundle this Release build embeds is outside it.
Rather than bolt a second hash onto the key to cover the JS, the build is now
repacked: @expo/repack-app rebuilds the bundle from current source and swaps it
into the cached app. Keying on the fingerprint alone is then exactly right, and
a JS-only change costs seconds instead of another ~22 minute build. Measured on
a real Release bundle: 13.5s, Hermes bytecode preserved, native binary byte
-identical. --js-bundle-only is precisely the gap the fingerprint leaves; every
other thing repack would refresh is hashed into the key already, so a hit proves
it unchanged.

Gitignoring /ios and /android is what makes this work across machines, and it is
all that is needed: @expo/fingerprint resolves the project workflow by asking the
VCS whether the platform markers are ignored, and appends `ios/**/*` and
`android/**/*` itself once it concludes CNG. The prebuild output exists on
developer machines but never in a fresh CI checkout, so without that the
fingerprint was machine-specific — ab99f403 locally against 14d08bcd in CI — and
no cache could ever have been shared between the two.

On top of that, serve developers the dev-client build from Actions artifacts
keyed on the same fingerprint, so a checkout with no native changes installs
CI's binary instead of building. iOS builds on a macOS runner, Android on a
Linux one. Android has no build-only mode — the CLI resolves a device before
gradle because a debug build is narrowed to that device's ABI — so the emulator
is there to satisfy it, and --all-arch opts out of the narrowing so the artifact
is not pinned to the emulator's x86_64. Every AVD on the maintainer's Apple
Silicon machine reports arm64-v8a only, so a single-ABI artifact could not serve
both it and CI.

Only CI publishes: GitHub has no API for creating an artifact outside a workflow
run, and the fingerprint does not capture the toolchain, so one known toolchain
is the only safe producer. The provider refuses release builds outright rather
than hand back a stale bundle, and a missing token or a failed lookup only ever
costs a local build.

The provider must set a User-Agent explicitly. @expo/cli replaces global fetch
with fetch-nodeshim, which sends none, and GitHub rejects those with a 403 —
which the error handling would otherwise have swallowed into "build locally"
forever.

Finally, `expo run:ios --output` replaces the DerivedData scan in the build
step. `find ... | head -1` picked an arbitrary bundle when more than one
matched; this machine has two Release-iphonesimulator AgentDeviceTester.app
builds, so that was reachable rather than theoretical.

Author: thymikee

.github/actions/setup-fixture-app/action.yml

@@ -3,14 +3,19 @@ description: "Build (or restore from cache) the examples/test-app fixture app an
 
 # Any job that needs a controlled app to drive can use this instead of an Apple
 # system app. Building it costs ~22 minutes, so the built .app is cached and the
-# build only runs when its sources or the toolchain actually change.
+# build only runs when the native inputs or the toolchain actually change.
 #
 # The cache is shared: GitHub caches are per-repository and readable across
 # workflows, and a run can restore caches from its own branch or the default
 # branch. So once a run on main populates it, every workflow gets the hit. The
 # key is computed here from a fixed input list, so all callers agree on it —
 # do not fold caller-specific inputs into it, or the cache stops being shared.
 #
+# Keyed on the Expo fingerprint, which hashes the native build and nothing else.
+# A hit therefore guarantees only that the native side is current, so the JS the
+# Release build embedded may be stale — @expo/repack-app swaps in a bundle built
+# from the current source, which takes seconds instead of another full build.
+#
 # Relevant to #320 (move replay coverage off system apps onto a stable fixture).
 
 inputs:
@@ -48,37 +53,47 @@ runs:
         XCODE_KEY="$(xcodebuild -version | tr '\n' ' ' | sed -E 's/[[:space:]]+/ /g; s/[[:space:]]$//' | tr ' ' '-' | tr -cd '[:alnum:]._-')"
         echo "key=$XCODE_KEY" >> "$GITHUB_OUTPUT"
 
+    # Installed even on a hit, because the fingerprint is derived from the
+    # dependency graph and cannot be computed without it.
+    - name: Install test app dependencies
+      shell: bash
+      run: pnpm test-app:install
+
+    - name: Resolve fingerprint cache key
+      id: fingerprint
+      shell: bash
+      run: |
+        set -euo pipefail
+        # No --platform: its default (android + ios) is what @expo/cli hashes for
+        # its own build cache, so this key agrees with what `expo run:*` looks up.
+        HASH="$(pnpm --dir examples/test-app exec fingerprint fingerprint:generate | jq -r .hash)"
+        echo "key=$HASH" >> "$GITHUB_OUTPUT"
+        echo "fingerprint: $HASH"
+
     - name: Cache fixture app build
       id: cache
       uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.2.3
       with:
         path: ${{ github.workspace }}/.tmp/fixture-app
-        # Everything that can change the binary: app sources, native config,
-        # dependency graph, this action's build logic, and the toolchain.
-        # Deliberately caller-independent so the cache is shared across workflows.
-        key: fixture-app-ios-${{ inputs.runtime-version }}-${{ steps.xcode.outputs.key }}-${{ hashFiles('examples/test-app/src/**', 'examples/test-app/app/**', 'examples/test-app/modules/**', 'examples/test-app/app.config.js', 'examples/test-app/package.json', 'examples/test-app/pnpm-lock.yaml', 'examples/test-app/pnpm-workspace.yaml', '.github/actions/setup-fixture-app/action.yml') }}
+        # The fingerprint, the toolchain it is built with, and this action's own
+        # build logic. Deliberately caller-independent so the cache is shared
+        # across workflows.
+        key: fixture-app-ios-${{ inputs.runtime-version }}-${{ steps.xcode.outputs.key }}-${{ steps.fingerprint.outputs.key }}-${{ hashFiles('.github/actions/setup-fixture-app/action.yml') }}
 
     - name: Build fixture app
       if: steps.cache.outputs.cache-hit != 'true'
       shell: bash
       run: |
         set -euo pipefail
         # Release embeds the JS bundle, so no Metro server is needed in CI.
-        pnpm test-app:install
+        # --output writes the bundle to the deterministic path the cache keeps,
+        # instead of leaving it under a per-project DerivedData hash. The CLI
+        # copies it before installing, so the simulator still gets this binary.
         pnpm --dir examples/test-app exec expo run:ios \
           --configuration Release \
           --device "${{ inputs.device-name }}" \
-          --no-bundler
-        # Stash the bundle at a stable path: DerivedData paths are hashed per
-        # project, so the cache needs somewhere deterministic to keep it.
-        APP_PATH="$(find "$HOME/Library/Developer/Xcode/DerivedData" -type d -name '*.app' -path '*Release-iphonesimulator*' | head -1)"
-        if [ -z "$APP_PATH" ]; then
-          echo "::error::Built the fixture app but could not locate its .app bundle to cache."
-          exit 1
-        fi
-        mkdir -p "${{ github.workspace }}/.tmp/fixture-app"
-        rm -rf "${{ github.workspace }}/.tmp/fixture-app/"*.app
-        cp -R "$APP_PATH" "${{ github.workspace }}/.tmp/fixture-app/"
+          --no-bundler \
+          --output "${{ github.workspace }}/.tmp/fixture-app"
 
     - name: Locate fixture app
       id: locate
@@ -87,7 +102,7 @@ runs:
         set -euo pipefail
         APP="$(find "${{ github.workspace }}/.tmp/fixture-app" -maxdepth 1 -type d -name '*.app' | head -1)"
         if [ -z "$APP" ]; then
-          echo "::error::No fixture app bundle at .tmp/fixture-app (restored an empty cache?)."
+          echo "::error::No fixture app bundle at .tmp/fixture-app (empty cache, or the build emitted nothing)."
           exit 1
         fi
         # Read the id from the bundle itself rather than duplicating it here, so
@@ -97,6 +112,30 @@ runs:
         echo "app-id=$APP_ID" >> "$GITHUB_OUTPUT"
         echo "fixture app: $(basename "$APP") ($APP_ID)"
 
+    # A hit means the native build is current but the bundle it embedded is from
+    # whenever that build ran. --js-bundle-only is exactly the gap the
+    # fingerprint leaves: everything else it would refresh is already hashed into
+    # the key, so a hit proves it unchanged.
+    - name: Repack the cached app with the current JS
+      if: steps.cache.outputs.cache-hit == 'true'
+      shell: bash
+      run: |
+        set -euo pipefail
+        APP="${{ steps.locate.outputs.app-path }}"
+        OUT="${{ github.workspace }}/.tmp/fixture-app-repacked/$(basename "$APP")"
+        rm -rf "$(dirname "$OUT")"
+        mkdir -p "$(dirname "$OUT")"
+        pnpm --dir examples/test-app exec repack-app \
+          --platform ios \
+          --source-app "$APP" \
+          --output "$OUT" \
+          --js-bundle-only
+        # Swap it into the path the cache restored, so the install step and the
+        # cached bundle stay one and the same. Safe to mutate: actions/cache does
+        # not write back on a hit.
+        rm -rf "$APP"
+        mv "$OUT" "$APP"
+
     - name: Install fixture app
       if: inputs.install == 'true'
       shell: bash

.github/workflows/test-app-build-cache.yml

@@ -0,0 +1,144 @@
+name: Test App Build Cache
+
+# Keeps a dev-client build of examples/test-app published as a workflow artifact
+# per platform, so `pnpm test-app:ios` and `pnpm test-app:android` install CI's
+# binary instead of running a native build. Only CI can publish: GitHub has no
+# API for creating an artifact outside a workflow run, so this is the sole
+# producer and every developer machine is a reader (see
+# examples/test-app/build-cache-provider.js).
+#
+# The artifact is keyed by the Expo fingerprint, which covers native inputs only.
+# Runs on every push to main, but builds only when that fingerprint has no
+# artifact yet -- on a hit the provider short-circuits the build and this costs a
+# couple of minutes. Artifacts expire after 90 days; the next run rebuilds.
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  # The provider lists and downloads artifacts through the REST API.
+  actions: read
+
+concurrency:
+  # One producer at a time, so the same fingerprint is never built twice over.
+  # Runs queue instead of cancelling: a long build would otherwise be killed by
+  # the next merge and the cache might never be populated at all. Queued runs are
+  # cheap — they find the artifact published and skip the build.
+  group: ci-${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  dev-client:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    strategy:
+      # The platforms are independent caches; one failing must not withhold the
+      # other's artifact.
+      fail-fast: false
+      matrix:
+        include:
+          - name: iOS dev client
+            platform: ios
+            runs-on: macos-26
+          - name: Android dev client
+            platform: android
+            runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup toolchain
+        uses: ./.github/actions/setup-node-pnpm
+
+      - name: Install test app dependencies
+        run: pnpm test-app:install
+
+      # `--device generic` builds for the simulator but skips install and launch,
+      # so no simulator has to be booted. The provider resolves the cache first:
+      # when the fingerprint already has an artifact it downloads it and the
+      # build is skipped, which also proves the cached artifact is still usable.
+      - name: Build the iOS dev client if this fingerprint is not cached yet
+        if: matrix.platform == 'ios'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pnpm --dir examples/test-app exec expo run:ios --device generic --no-bundler
+
+      - name: Setup Android host
+        if: matrix.platform == 'android'
+        uses: ./.github/actions/setup-android-replay-host
+
+      - name: Install Android SDK packages
+        if: matrix.platform == 'android'
+        run: |
+          set -euo pipefail
+          SDK_ROOT="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-/usr/local/lib/android/sdk}}"
+          SDKMANAGER="$SDK_ROOT/cmdline-tools/latest/bin/sdkmanager"
+          if [ ! -x "$SDKMANAGER" ]; then
+            SDKMANAGER="$SDK_ROOT/cmdline-tools/bin/sdkmanager"
+          fi
+          yes | "$SDKMANAGER" --licenses >/dev/null
+          "$SDKMANAGER" "platforms;android-36" "build-tools;36.0.0"
+
+      # Android has no build-only mode: the CLI resolves a device before gradle,
+      # because a debug build is narrowed to that device's ABI. --all-arch opts
+      # out of that narrowing, which is what makes the artifact usable on any
+      # developer's device rather than only on this emulator's x86_64. The
+      # emulator is here to satisfy the CLI, and installs the result as a bonus
+      # check that the published APK is loadable.
+      - name: Build the Android dev client if this fingerprint is not cached yet
+        if: matrix.platform == 'android'
+        uses: reactivecircus/android-emulator-runner@b530d96654c385303d652368551fb075bc2f0b6b # v2.35.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          api-level: 36
+          arch: x86_64
+          profile: pixel_7
+          target: google_apis_playstore
+          emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim -no-metrics
+          script: |
+            set -e
+            pnpm --dir examples/test-app exec expo run:android --no-bundler --all-arch
+
+      # The provider writes this only when it actually built something, so its
+      # presence is what decides whether there is anything new to publish. The
+      # name comes from the provider so the artifact can only be published under
+      # the name the provider looks up.
+      - name: Stage the build for upload
+        id: stage
+        run: |
+          set -euo pipefail
+          INTENT=examples/test-app/.expo/remote-build-cache-upload.json
+          if [ ! -f "$INTENT" ]; then
+            echo "This fingerprint is already cached; nothing to publish."
+            exit 0
+          fi
+          NAME="$(node -p "JSON.parse(require('fs').readFileSync('$INTENT', 'utf8')).name")"
+          BUILD_PATH="$(node -p "JSON.parse(require('fs').readFileSync('$INTENT', 'utf8')).buildPath")"
+          # A .app is a directory and an .apk is a file, so only test existence.
+          if [ ! -e "$BUILD_PATH" ]; then
+            echo "::error::Provider reported a build at $BUILD_PATH but there is nothing there."
+            exit 1
+          fi
+          # Tar the binary: artifact zips drop the executable bit, which would
+          # leave an installed .app unable to launch.
+          mkdir -p .tmp/test-app-build-cache
+          tar -czf .tmp/test-app-build-cache/app.tar.gz \
+            -C "$(dirname "$BUILD_PATH")" "$(basename "$BUILD_PATH")"
+          echo "name=$NAME" >> "$GITHUB_OUTPUT"
+          echo "publishing $NAME ($(du -h .tmp/test-app-build-cache/app.tar.gz | cut -f1))"
+
+      - name: Publish to the build cache
+        if: steps.stage.outputs.name != ''
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ${{ steps.stage.outputs.name }}
+          path: .tmp/test-app-build-cache/app.tar.gz
+          if-no-files-found: error
+          compression-level: 0 # already gzipped

examples/test-app/.gitignore

@@ -1,2 +1,7 @@
 .expo/
 node_modules/
+
+# Generated by `expo prebuild`. Ignoring them is also what makes
+# @expo/fingerprint treat this project as CNG and skip hashing them.
+/ios
+/android

examples/test-app/README.md

@@ -52,6 +52,31 @@ The app declares `@expo/dom-webview` directly to keep Expo's development runtime
 on the SDK 56 native module; Android verification failed when the dev client
 resolved an older transitive copy.
 
+### Build cache
+
+`pnpm test-app:ios` and `pnpm test-app:android` install the build CI already made
+instead of running a full native build, unless you changed something native. It
+is keyed by the [Expo fingerprint](https://docs.expo.dev/versions/latest/sdk/fingerprint/),
+which covers native inputs only: app config, dependencies, autolinking, and the
+local modules' native code. Editing screens never needs a rebuild, because Metro
+serves JavaScript at runtime.
+
+That fingerprint is why `/ios` and `/android` are gitignored: ignoring the
+prebuild output is what makes @expo/fingerprint treat this app as CNG and skip
+hashing it. Un-ignore them and the fingerprint starts describing your machine
+rather than the project, and nothing will ever hit the cache.
+
+Reading the cache needs a GitHub token. `gh auth login` provides one; `GITHUB_TOKEN`
+or `GH_TOKEN` is used first if set. Without a token, `expo run:*` says so and
+builds locally as before — the cache only ever saves time, it is never required.
+
+Only CI writes to it, in `.github/workflows/test-app-build-cache.yml`: GitHub has
+no API for creating a workflow artifact outside a workflow run. iOS is built on a
+macOS runner and Android on a Linux one, so a native change costs one build per
+platform on `main` and every developer downloads the result. Dev-client builds
+for simulators and emulators only; a release build embeds its own JS bundle,
+which the fingerprint does not describe, so the cache declines to serve one.
+
 ### iOS simulator
 
 From the repo root, install dependencies and run the development build on the

examples/test-app/app.config.js

@@ -1,8 +1,5 @@
 const accessorySetupConfig = require('./accessory-setup.config.json');
 
-const buildRunCacheDir =
-  process.env.AGENT_DEVICE_EXPO_BUILD_CACHE_DIR?.trim() || './.expo/build-run-cache';
-
 const accessoryInfoPlist = {
   NSAccessorySetupBluetoothServices: [accessorySetupConfig.serviceUuid],
   NSAccessorySetupKitSupports: ['Bluetooth'],
@@ -17,9 +14,10 @@ module.exports = {
     orientation: 'default',
     userInterfaceStyle: 'automatic',
     buildCacheProvider: {
-      plugin: 'expo-build-disk-cache',
+      plugin: './build-cache-provider.js',
       options: {
-        cacheDir: buildRunCacheDir,
+        owner: 'callstack',
+        repo: 'agent-device',
       },
     },
     plugins: ['expo-router'],