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)¶
- Match the toolchain matrix (rbenv/nvm/Xcode as needed).
task native:setup—bundle install(fastlane + cocoapods, pinned).gcloud auth loginandgcloud auth application-default login(the second is whatmatch's GCS storage reads).- Android: JDK 17 (
brew install --cask temurin@17) and the Android SDK (Android Studio installs it to~/Library/Android/sdk), then exportANDROID_HOMEin your shell profile:Gradle needsecho 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrcANDROID_HOME; alocal.propertieswon't do (each build'sexpo prebuild --cleanregeneratesandroid/). 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 infrontend/native-build.jsonas monotonic integers (stores reject a reused value, so every binary needs a fresh one even at the same marketing version).Every build task runstask native:version:build # +build number / versionCode (same marketing version) task native:version:bump -- patch # + marketing version (patch|minor|major)native:version:buildfor you, dev and prod alike, so the two share one counter.app.config.jsreads all three at build time.native-build.jsonalso records each platform's prod build (number and marketing version) underproduction. Commit it (andpackage.jsonon 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 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):
- Add the dev upload key as the GitHub Actions secret
XAVIA_DEV_UPLOAD_KEY(repo → Settings → Secrets and variables → Actions):The prod key stays in Secret Manager;gcloud secrets versions access latest --secret=tomoda-ota-dev-upload-key --project=development-485000ota.ymlreads it onmainonly, as thetomoda-releaseservice account through WIF. - Set the repo variable
OTA_ENABLED=true(same page → Variables). - Confirm the Xavia dev deployment is configured with
tomoda-ota-signing-key(else the code-signed binary rejects every update). - Cut a fresh Android beta so the shipped binary carries
expo-updatesand its new fingerprint, and commit the refreshednative-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:
- Bump the SDK/dep; run
npx expo install --fix; updatepackage-lock.json. - Update the toolchain matrix above + the pin files if the SDK requires new Xcode/JDK/CocoaPods versions.
npx expo prebuild --cleanlocally to shake out native config issues.- Expect a new
runtimeVersion: existing binaries won't receive further OTA until a new binary ships. task native:doctor, then cut a fresh beta on both platforms and commitnative-build.json+native-fingerprint.dev.*.txt. Ship prod builds from the next release tag.
See also¶
- Signing — match on GCS, upload keystore, Play App Signing, the secret inventory, first-time setup.
- App Store / Play Store — portal-side management.
- Native Testing — simulator / device QA.