Skip to content

Native Release

The Tomoda native iOS and Android apps are built and submitted from a developer Mac with fastlane, no EAS. Every build runs through a single entrypoint so any set-up Mac produces the same signed binary: Taskfile → scripts/release/build-with-secrets.sh → bundle exec fastlane. Signing is shared and reproducible (iOS via fastlane match, Android via a shared upload keystore), and all secrets come from GCP Secret Manager.

This page is the conceptual + operational flow. For the signing material and the one-time credential setup, see Signing. For portal-side store management see App Store and Play Store.

The model

Layer Ships When How
Native binary .ipa / .aab native dep/SDK change, or a store submission fastlane (below) → TestFlight / Play
OTA JS bundle JS + assets every other merge expo export --platform ios --platform android → Xavia (OTA)

ios/ and android/ are not committed — every build regenerates them from app.config.js (expo prebuild --clean), so nothing machine-local leaks in.

Reproducibility: the toolchain matrix

Reproducible builds require every machine to run the same tool versions. These are pinned in the repo; treat this table as the source of truth and update it (plus the pin files) together.

Tool Version Pinned in
Node 24.15.0 frontend/.nvmrc
Ruby 4.0.5 frontend/.ruby-version
Xcode 26.6 frontend/.xcode-version
JDK 17 (Temurin) installed locally (One-time setup)
CocoaPods ~1.16 frontend/Gemfile
fastlane ~2.226 frontend/Gemfile
Expo SDK / RN pinned frontend/package-lock.json

task native:doctor checks the installed toolchain against these, that gcloud is authenticated, and that the signing secrets are reachable. Run it first on any new machine.

One-time setup (per machine)

  1. Match the toolchain matrix (rbenv/nvm/Xcode as needed).
  2. task native:setup — bundle install (fastlane + cocoapods, pinned).
  3. gcloud auth login and gcloud auth application-default login (the second is what match's GCS storage reads).
  4. Android: JDK 17 (brew install --cask temurin@17) and the Android SDK (Android Studio installs it to ~/Library/Android/sdk), then export ANDROID_HOME in your shell profile:
    echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
    
    Gradle needs ANDROID_HOME; a local.properties won't do (each build's expo prebuild --clean regenerates android/).
  5. task native:doctor — expect all green except lanes you haven't set up yet.

First-time credential setup (match bucket, keystore, ASC key, Play service account) is a separate, mostly one-person job — see Signing.

Lanes: dev beta and prod store build

There are two kinds of binary. They differ only in the URLs baked in at build time, which scripts/release/build-with-secrets.sh sets per lane, so a binary always talks to one backend and one OTA server:

Task fastlane lane Bakes in Uploads to Fingerprint file
task native:beta:ios ios beta api-dev, ota-dev TestFlight internal native-fingerprint.dev.ios.txt
task native:beta:android android beta api-dev, ota-dev Play Internal testing native-fingerprint.dev.android.txt
task native:prod:ios ios production api, ota TestFlight internal native-fingerprint.prod.ios.txt
task native:prod:android android production api, ota Play Internal testing native-fingerprint.prod.android.txt
task native:release:ios ios release (no build) submits the recorded prod build for App Store review
task native:release:android android release (no build) promotes the recorded prod build to Production, 10% staged rollout

task native:beta and task native:prod run both platforms. Each build task runs node scripts/release/bump-version.js build, which takes the higher of the checkout's and origin/main's build numbers (as last fetched) and adds one, then ./scripts/release/build-with-secrets.sh <beta|prod>-<platform>, which pulls the secrets and runs bundle exec fastlane <platform> <beta|production>. The lane regenerates ios/ or android/ (expo prebuild --clean), signs, uploads, and writes the binary's fingerprint (its OTA runtimeVersion) to its env's file. A production lane also records the uploaded build number and marketing version in native-build.json under production.<platform>; the release lanes promote exactly that build, never a dev beta. A lane refuses to run with the other env's URLs.

Dev betas and prod builds share the internal tracks, so internal testers get whichever was uploaded last. A prod build there is the exact binary that goes to the stores, against the prod backend.

Cutting a dev beta

Betas are the dev-facing channels, built from main whenever a native change needs testing:

git switch main && git pull
task native:doctor
task native:beta:ios        # dev .ipa -> TestFlight internal
task native:beta:android    # dev .aab -> Play Internal testing
git commit -m "chore(native): dev beta build $(node -p "require('./frontend/native-build.json').versionCode")" \
  frontend/native-build.json frontend/native-fingerprint.dev.ios.txt frontend/native-fingerprint.dev.android.txt
git push

Testers update through TestFlight / the Play Store. iOS internal groups skip beta review; external groups need Beta App Review on first submission. Merges to main then reach these binaries over OTA from ota-dev.

Shipping to the stores from a release tag

A store binary is built from the vX.Y.Z tag the Release workflow cut, so the binary, the prod images and the prod OTA bundle all come from one commit (see Deployment → Releasing). Build it after the release's deploy PR is merged, so the binary meets the backend it was built against. Both platforms are built on a developer Mac.

On a Mac set up per One-time setup:

git fetch origin --tags      # origin/main: build numbers continue from main's
git switch --detach v1.2.3
task native:doctor
task native:prod:ios         # prod .ipa -> TestFlight internal, recorded for release
scripts/release/native-commit.sh ios prod
git switch --detach v1.2.3
task native:prod:android     # prod .aab -> Play Internal testing, recorded for release
scripts/release/native-commit.sh android prod
git switch main && git pull --ff-only

native-commit.sh commits the bumped native-build.json and the platform's prod fingerprint onto the latest main and pushes: build numbers take the higher value, and only this platform's production entry is taken, so it never conflicts with builds made meanwhile. It refuses to run while other files have uncommitted changes, and leaves you on a native-commit branch.

Vet the build on the internal tracks against prod, then promote it (no rebuild):

task native:release:ios       # submit the recorded prod build for App Store review
task native:release:android   # promote the recorded prod build to Production (10% staged rollout)

See App Store / Play Store for the portal steps (metadata, review, staged rollout). Once the store build is live, prod OTA from later releases reaches it.

Versioning — two numbers, don't conflate them

  • Marketing version (frontend/package.json, e.g. 1.2.3) — what the stores show. The iOS build number + Android versionCode live in frontend/native-build.json as monotonic integers (stores reject a reused value, so every binary needs a fresh one even at the same marketing version).
    task native:version:build              # +build number / versionCode (same marketing version)
    task native:version:bump -- patch      # + marketing version (patch|minor|major)
    
    Every build task runs native:version:build for you, dev and prod alike, so the two share one counter. app.config.js reads all three at build time. native-build.json also records each platform's prod build (number and marketing version) under production. Commit it (and package.json on a bump) after every build. None of these numbers feed the fingerprint (frontend/fingerprint.config.js), so a new build never cuts older binaries off OTA.
  • Deployment tag (vX.Y.Z): the backend + web release and the prod OTA publish, cut by the Release workflow. Independent of the marketing version; build store binaries from the tag (Shipping to the stores).

OTA updates (self-hosted)

Native binaries are built rarely (only on a native change). Most merges are pure JS/TS and ship over-the-air via a self-hosted Xavia OTA server (expo-updates manifest server, deployed in-cluster). No store round-trip.

app.config.js uses runtimeVersion: { policy: "fingerprint" }, computed from the native project. Any native change → a different fingerprint → a different runtimeVersion, and an OTA bundle only reaches binaries whose runtimeVersion matches. So a native change can never crash an old binary via OTA; it simply needs a fresh binary. No one bumps a version by hand.

The fingerprint covers the native project and the app config, including the baked-in URLs, so iOS and Android differ and dev and prod differ. Build numbers and the marketing version are left out (frontend/fingerprint.config.js). Each pair is tracked in its own file, frontend/native-fingerprint.<env>.<platform>.txt, written by the lane that built that env's current binary. The OTA workflow computes both platforms' runtimeVersions with its env's URLs, publishes the same JS bundle under each (Xavia serves the right per-platform bundle by runtimeVersion), and per platform compares to that env's file: unchanged → the bundle reaches existing binaries; changed → it opens a "Native rebuild needed" issue; missing → no binary of that env is recorded yet. Two servers, baked at build time via EXPO_PUBLIC_OTA_URL: ota-dev.tomoda.life (beta lanes; every merge to main) and ota.tomoda.life (production lanes; each release, once its deploy PR is merged).

Manifests are code-signed: the binary carries the public cert (frontend/certs/ota-public.pem) and the Xavia server signs each manifest with the private key (tomoda-ota-signing-key). An unsigned manifest is rejected, so the Xavia deployment must hold that key.

Enabling OTA

expo-updates is a dependency, so a fresh binary carries the OTA runtime. To turn on publishing (the OTA workflow is dormant until then):

  1. Add the dev upload key as the GitHub Actions secret XAVIA_DEV_UPLOAD_KEY (repo → Settings → Secrets and variables → Actions):
    gcloud secrets versions access latest --secret=tomoda-ota-dev-upload-key --project=development-485000
    
    The prod key stays in Secret Manager; ota.yml reads it on main only, as the tomoda-release service account through WIF.
  2. Set the repo variable OTA_ENABLED=true (same page → Variables).
  3. Confirm the Xavia dev deployment is configured with tomoda-ota-signing-key (else the code-signed binary rejects every update).
  4. Cut a fresh Android beta so the shipped binary carries expo-updates and its new fingerprint, and commit the refreshed native-fingerprint.dev.android.txt.

After that, a merge to main publishes JS to ota-dev on the Android runtimeVersion, and Internal-testing devices update on next launch.

Upgrading the Expo SDK (or any native dep)

A native dependency bump changes the fingerprint, so it needs a fresh binary:

  1. Bump the SDK/dep; run npx expo install --fix; update package-lock.json.
  2. Update the toolchain matrix above + the pin files if the SDK requires new Xcode/JDK/CocoaPods versions.
  3. npx expo prebuild --clean locally to shake out native config issues.
  4. Expect a new runtimeVersion: existing binaries won't receive further OTA until a new binary ships.
  5. task native:doctor, then cut a fresh beta on both platforms and commit native-build.json + native-fingerprint.dev.*.txt. Ship prod builds from the next release tag.

See also