The whole flow on one page
One command, two stores, one build number. The left half already exists and ships today; the right half is what this plan builds.
┌────────────────────────────────┐
│ Someone tells NOVA: │
│ cut build N │
└───────────────┬────────────────┘
│
┌───────────────┴────────────────┐
│ GATE 1 CHANGELOG has a │
│ section naming N │
├────────────────────────────────┤
│ GATE 2 that section is on │
│ origin/master AND │
│ matches word for word │
└───────────────┬────────────────┘
│ both pass
│
┌────────────────────┴────────────────────┐
│ SEQUENTIAL, not parallel │
│ both builds write into app/build and │
│ share .dart_tool — run at once in one │
│ checkout and they corrupt each other │
└────────┬───────────────────────┬────────┘
│ │
┌─────────┴────────┐ ┌─────────┴─────────┐
│ iOS (EXISTS) │ │ ANDROID (NEW) │
├──────────────────┤ ├───────────────────┤
│ unlock keychain │ │ read key.properties│
│ build ipa │ │ build appbundle │
│ unzip, verify │ │ unzip, verify │
│ CFBundleVersion │ │ versionCode == N │
│ altool upload │ │ Play API upload │
│ wait VALID │ │ (no review wait) │
│ add 2 groups │ │ internal track │
│ + READ BACK │ │ + READ BACK │
│ whatsNew │ │ release notes │
│ + READ BACK │ │ + READ BACK │
│ submit review │ │ roll out 100% │
└─────────┬────────┘ └─────────┬─────────┘
│ │
└───────────┬───────────┘
│
┌───────────────┴────────────────┐
│ ANNOUNCE — one line per store │
│ never a single combined OK │
│ iOS ✅ / Android ❌ must be │
│ sayable in the same message │
└───────────────┬────────────────┘
│
┌─────────────────────┴─────────────────────┐
│ │
┌──────────┴───────────┐ ┌─────────────┴────────────┐
│ Tester on iPhone │ │ Tester on Android │
│ TestFlight notifies │ │ Play Store updates it │
│ → taps Update │ │ → like any other app │
└──────────────────────┘ └──────────────────────────┘
The one principle carried over from iOS: every claim the pipeline makes about itself
must be backed by something it read back. The iOS pipeline learned this the hard way — a version of it once
announced APPROVED to the whole company based on an exit code, while the thing it claimed had not happened.
Each
+ READ BACK above is a scar, not decoration.Why one number for both stores
Your call on 2026-09-17: shared. Build 231 means the same commit on both stores.
Apple needs CFBundleVersion to rise per upload; Play needs versionCode to rise per upload.
A single counter satisfies both, and makes "which build is this" answerable in one place instead of two.
Cost of the choice, stated plainly: if one store rejects an upload and the other accepts it, the number is consumed on both. We skip a number rather than reuse one. Numbers are free; ambiguity is not.
What exists today, and what does not
Someone built the Android build half deliberately on 2026-09-09. That work is real and it holds up. What is missing is a key, an account, and the whole distribution half.
| Piece | State | Evidence |
|---|---|---|
| Android project (35 files, real Kotlin plugins) | EXISTS | app/android/ — CameraX, ML Kit text + face |
| Release signing wired into Gradle | EXISTS | app/android/app/build.gradle.kts reads key.properties |
| Missing key → debug fallback so any machine can build | EXISTS | Deliberate: nobody is blocked by not holding the key |
| Key present but incomplete → hard failure | EXISTS | Refuses to silently produce a debug-signed build that looks official |
| Key template committed, no real values | EXISTS | app/android/key.properties.example |
| Signing documentation | EXISTS | docs/ANDROID_RELEASE_SIGNING.md, written 09-09 |
| applicationId | EXISTS | com.hoop.hoop — permanent at first upload |
| The keystore itself | YOURS | By design, only you generate and hold it |
| Google Play developer account | YOURS | No trace anywhere in the repo |
| Android OAuth client for Google sign-in | MISSING — BREAKS LOGIN | See the warning below |
| Android build script | TO BUILD | Nothing exists |
| Play upload / distribution automation | TO BUILD | Nothing exists |
| Android row in the deployment table | TO BUILD | CLAUDE.md has no Android row at all |
⚠️ Google sign-in will not work on Android as things stand.
The login screen offers Google sign-in (
The trap inside the trap. With Play App Signing enabled, the app a tester installs is signed by Google's certificate, not by your upload key. So the SHA-1 to register is the app signing certificate from Play Console → Setup → App integrity — not the one from the keystore you generate. Register the wrong one and it works on a build you sideload and fails for every tester coming through Play, with an unhelpful error.
This is why the SHA-1 step in ③ sits after the first upload: it cannot be done before Play has generated that certificate. Left undiscovered, this surfaces as "testers cannot log in" only after everything else is finished.
The login screen offers Google sign-in (
login_screen.dart:338, account_screen.dart:330).
app/lib/api/google_signin.dart holds an iOS client ID and a Web client ID.
There is no Android client anywhere in the repo, and no google-services.json.
On Android, Google sign-in needs its own OAuth client registered against the package name plus the
SHA-1 of the certificate that signs the app.The trap inside the trap. With Play App Signing enabled, the app a tester installs is signed by Google's certificate, not by your upload key. So the SHA-1 to register is the app signing certificate from Play Console → Setup → App integrity — not the one from the keystore you generate. Register the wrong one and it works on a build you sideload and fails for every tester coming through Play, with an unhelpful error.
This is why the SHA-1 step in ③ sits after the first upload: it cannot be done before Play has generated that certificate. Left undiscovered, this surfaces as "testers cannot log in" only after everything else is finished.
Why the deployment table matters more than it looks
The web version once sat 20 days and a hundred versions stale because there was no row for it in the
deployment table in CLAUDE.md. Nobody was lazy — people follow the table, and what is not in the
table does not get remembered. Android has no row today. Adding one is task 4.2 and it is not paperwork.
One-time setup — who does what, and where
Four places. Parts 1 and 2 block everything else, so start them first; the account approval clock is the long pole and it is outside our control.
Part 1 · Your Mac, Terminal
$ keytool -genkey -v \
-keystore ~/.hoop-keys/hoop-release.jks \
-keyalg RSA -keysize 2048 -validity 10000 \
-alias hoop
Enter keystore password: ********
What is your first and last name? HOOP
...
[Storing ~/.hoop-keys/hoop-release.jks]
-validity 10000 is not arbitrary. Play requires the certificate to stay valid beyond
2033-10-22. If it expires, this app can never publish again. Do not shorten it.
Back up the file and its password to two separate places. Lose either and this app can never be updated again — there is no recovery path, only a new listing with zero users.
Back up the file and its password to two separate places. Lose either and this app can never be updated again — there is no recovery path, only a new listing with zero users.
Part 2 · Google Play Console play.google.com/console
play.google.com/console/signup
Create developer account
Account type
Organisation or personal
Registration fee
US$25, one time
Identity verification
Documents, then a wait
Pay and continue
2.1 · Account YOU — the long pole.
Approval is measured in days and nothing else can finish until it clears. Start here.
play.google.com/console/app/create
Create app
App name
HOOP
Package name
com.hoop.hoop — permanentPlay App Signing
Offered once. Turn it ON.
Create app
2.2–2.4 · Two permanent choices YOU —
the package name and Play App Signing are both locked from first upload. Neither can be changed later.
…/console/app/app-content
App content
Privacy policy URL
Usually the blocker — have one ready
Data safety
Camera, coarse location declared;
plugins add mic, photos, files
Content rating
Questionnaire
Target audience · Ads
Declarations
2.5 · Declarations YOU — answer for what the app
actually collects and sends. The manifest declares CAMERA and ACCESS_COARSE_LOCATION;
plugins merge in more.
…/console/testing/internal
Internal testing
Testers
Email list — Google accounts only
Limit
Up to 100
Review
None on this track
Opt-in link
play.google.com/apps/internaltest/…
2.6–2.8 · The track YOU — this is the
TestFlight equivalent. No review means minutes, not days.
Part 3 · Google Cloud Console console.cloud.google.com
| # | Step | Why |
|---|---|---|
| 3.1 | Create or pick a project | Reuse the one owning client ID 584364169898 so all HOOP OAuth lives together |
| 3.2 | Enable the Google Play Android Developer API | Without it, uploads must be done by hand |
| 3.3 | Create a service account, create a JSON key, download it | The pipeline's credentials |
| 3.4 | Note the service account email | Needed to grant it access in Play Console |
| 3.5 | Create an Android OAuth client: com.hoop.hoop + SHA-1 |
Fixes Google sign-in. SHA-1 comes from Play Console → Setup → App integrity, after the first upload. Optionally add a second client with the upload key's SHA-1 so sign-in also works on sideloaded builds. |
Part 4 · Back in Play Console — linking the two
| # | Step | Note |
|---|---|---|
| 4.1 | Setup → API access → link the Cloud project | Spans both consoles; easy to miss |
| 4.2 | Grant the service account release-to-testing-tracks permission | Do not grant production release rights yet |
Part 5 · NOVA's build machine
| # | Step | Note |
|---|---|---|
| 5.1 | Put the .jks outside the repo (~/.hoop-keys/) | Never inside app/android/ |
| 5.2 | Create app/android/key.properties, four values | Never enters git |
| 5.3 | Put the service account JSON outside the repo | Same rule |
| 5.4 | flutter doctor --android-licenses |
The mac mini reports these unaccepted today; NOVA's machine needs its own check |
| 5.5 | Confirm JDK 17 | Gradle config targets 17 |
Secrets travel as files, not as messages. Put them directly on the machine.
Do not paste keystore passwords or the service account JSON into HOOP chat — message history retains them,
and the pipeline never needs a human to relay a secret.
The build — what NOVA does, and what it prints
One command, detached from the session. The iOS pipeline exists because builds outlive the agent conversation that started them: packages once sat finished and unsent for six hours because the step that said "now upload it" was still attached to a session that had ended.
What is typed
# same shape as iOS today — detached, survives the session dying
$ python3 -c "import subprocess, os
subprocess.Popen(['/bin/bash', os.path.expanduser('~/.hoop/nova/build/cut_build.sh'),
'231', '/Users/Shared/wt/nova/build231'],
stdout=open('/tmp/cut231.log','w'), stderr=subprocess.STDOUT,
start_new_session=True)"
Not
nohup setsid. macOS has no setsid; that command prints one line
and the pipeline never starts. It has already cost one build. start_new_session=True, then
verify the process is alive and the log is growing — "I launched it" is not "it is running".What the log looks like when it goes well
[08:12:03] ✅ CHANGELOG gate passed
[08:12:05] ✅ build 231 section is on master, text identical
[08:12:06] 🔨 iOS flutter build ipa --build-number=231
[08:31:44] ✅ unzipped, CFBundleVersion = 231
[08:34:19] ✅ upload UPLOAD SUCCEEDED
[08:41:02] ✅ VALID · 2 groups added and read back · notes written and read back
[08:41:20] ✅ Beta review APPROVED
[08:41:21] 🔨 Android flutter build appbundle --build-number=231
[08:49:55] ✅ unzipped, versionCode = 231
[08:50:31] ✅ uploaded to internal track
[08:50:38] ✅ release notes written and read back (412 chars)
[08:50:44] ✅ rolled out 100% · read back: track internal, versionCode 231
[08:50:45] 🎉 build 231 complete — iOS APPROVED · Android LIVE on internal
What it looks like when one store fails
[08:41:20] ✅ iOS Beta review APPROVED
[08:49:55] ✅ Android versionCode = 231
[08:50:31] 🛑 Android upload rejected: versionCode 231 already used
[08:50:31] 🛑 stopping before rollout — nothing partial left on the track
This is the case the design is actually for. iOS succeeded and Android did not.
A single combined "done" would be a lie in both directions. The announcement must be able to say
one succeeded and one failed in the same message, and the General-room post must stay silent
unless the thing it claims is true.
The two announcements
📦 build 231 complete
Posted by the pipeline, not by a session.
iOS · TestFlight
APPROVED · groups read back · notes written
Android · Play internal
LIVE · rolled out 100% · read back OK
Both lines come from the log, not from a template.
1 · Build room TO BUILD —
one line per store. Always posted, success or failure.
⚠️ build 231 — half landed
One store is live, one is not.
iOS · TestFlight
APPROVED — testers can update
Android · Play internal
FAILED at upload — nothing on the track
Do not tell Android testers anything yet. Log: /tmp/cut231.log
2 · Partial failure TO BUILD —
the shape that matters. Never a green tick covering both.
Build 231 is live for testers
iOS and Android.
iPhone
Open TestFlight and update
Android
Play Store will update it, or open the app page
Posted automatically by the build pipeline.
3 · General TO BUILD —
mandated by Li Min 2026-09-02 for every approved build. Posted only when the log proves
both stores really succeeded; otherwise the whole-company room stays silent.
The tester — first install, then every update after
This is the half that decides whether the whole thing was worth building. Requirement 5 was "testers receive subsequent builds through the same mechanism" — that rules out sending APK files, and it is why Play internal testing wins over every alternative.
You are invited to test HOOP
Sent once, by you, from Play Console.
Open the opt-in link
play.google.com/apps/internaltest/…
Must be opened while signed in with the Google account you listed.
A different account silently sees nothing.
Accept invitation
1 · Opt-in ONE TIME —
the only manual step in a tester's whole life. TestFlight has the same beat.
H
HOOP
Internal test · build 231
Install
What's new
Read straight from CHANGELOG — the same text the iOS testers see
No review wait on this track. Minutes after the pipeline finishes.
2 · Install FIRST TIME —
from the Play Store the tester already has. No separate app, unlike Firebase.
Update available
Build 232 · 4 days later
H
HOOP
231 → 232
Update
Auto-update on means it simply appears. This is requirement 5,
and it costs the tester nothing.
3 · Every build after THE POINT —
ordinary app updates forever. Arguably smoother than TestFlight.
Sign in
First launch after install.
Continue with Google
⚠️ Fails today
No Android OAuth client registered. Needs task 1.4 done first,
using the Play app signing SHA-1.
Email OTP still works. But a tester hitting this
will report "login is broken", not "OAuth client missing".
4 · The one that bites BLOCKER —
invisible until a real tester on a real Play build taps it.
Why not Firebase App Distribution. It is free, needs no developer account, and could run
this week. But testers install a separate "App Tester" app and updates arrive through that, not through the
Play Store — so it is a different mechanism that we would later replace, meaning distribution gets built twice.
Your call on 2026-09-17 was to wait for Play. This plan reflects that.
Build plan — 4 phases, 18 tasks
Each task is separately trackable and has one objective. Nothing here is started. Phase 0 is yours and blocks the rest; phases 1–3 are mine.
Phase 0 · Accounts and keys YOU
Blocks everything. The account approval wait is the long pole — start 0.2 first, today.
| # | Task | Done when |
|---|---|---|
| 0.1 YOU | Generate the keystore, back it up twice, keep it outside the repo | Two independent backups exist, one of them not on your Mac |
| 0.2 YOU | Google Play developer account, US$25, identity verification | Console lets you create an app |
| 0.3 YOU | Create the app · Play App Signing ON · confirm com.hoop.hoop |
Both permanent choices made deliberately, not clicked past |
| 0.4 YOU | App content declarations, privacy policy URL | Internal testing track can accept a release |
| 0.5 YOU | Cloud project · enable Play Developer API · service account + JSON key | JSON key downloaded |
| 0.6 YOU | Link Cloud project in Play Console, grant the service account testing-track rights | Not production rights — testing only |
Phase 1 · First build by hand ME + A PHONE
Prove the thing works at all before automating it. This phase is where reality gets a vote.
| # | Task | Done when |
|---|---|---|
| 1.1 | Place keystore + key.properties + service account JSON on NOVA's machine;
accept SDK licences; confirm JDK 17 |
:app:signingReport shows Config: release pointing at the real key |
| 1.2 | First real signed .aab and .apk |
The .aab is signed by the real key, not debug — verified from the artifact |
| 1.3 RISK | Install on a real Android phone and use it | App opens, camera works, a message sends. Nothing in this project has ever run on Android hardware. |
| 1.4 BLOCKER | Android OAuth client with the Play app signing SHA-1; add the client ID to
google_signin.dart |
Google sign-in works on a build installed from Play, not just sideloaded |
| 1.5 | First upload to the internal track, by hand | One tester installs from Play and opens it |
1.3 is the task not to compress. Everything after it assumes the app actually works on
Android. The build config has been verified to compile and to pick the right signing path — that is all.
No real-key build exists and no Android phone has opened this app. First contact always surfaces
something nobody could predict from source.
Phase 2 · Automate it ME
Only after phase 1 proves the manual path. Automating an unproven path just hides where it breaks.
| # | Task | Done when |
|---|---|---|
| 2.1 | play_versions.py — highest versionCode on the track, pick next |
Mirrors asc_builds.py; agrees with the iOS counter |
| 2.2 | cut_android.sh — build, verify versionCode out of the artifact,
reuse both CHANGELOG gates |
A deliberately wrong build number is caught by unzipping the .aab, not by trusting the log |
| 2.3 | play_publish.py — upload, notes, rollout, each with read-back |
Every write is followed by a read that proves it landed |
| 2.4 | Merge into one command: iOS then Android, sequential | They never run concurrently in one checkout |
| 2.5 | Per-store announcements; General only when the log proves both | Forcing a half-failure produces the half-failure message, not a green tick |
Phase 3 · Make it stick ME
The parts that stop it rotting in a month.
| # | Task | Done when |
|---|---|---|
| 3.1 | Android row in the CLAUDE.md deployment table |
Someone who only reads the table still ships Android |
| 3.2 | Update docs/ANDROID_RELEASE_SIGNING.md for the automated path |
Same commit as the code — a doc that lags is a doc that lies |
| 3.3 | Deliberately broken runs: wrong build number, bad key, revoked service account | Each fails loudly at the right step. An untested gate is not a gate. |
| 3.4 | End-to-end rehearsal, then a second build | A tester receives the update without being told to do anything |
Why 3.4 needs two builds. The first proves install. Only the second proves the
update path — which is the actual requirement. Plenty of distribution setups install fine once
and never update again; that failure is invisible if you only ever ship one build.
Deliberately not scheduled
- Closed / open testing and production release. Those need review and more declarations. Internal testing is the TestFlight equivalent and is where this stops.
- Firebase App Distribution. Ruled out on 2026-09-17 — building distribution twice to save a wait.
- CI-hosted builds. Android could build on
ubuntu-latestwhere iOS cannot, but splitting the two across machines breaks the shared build number and the single command. Not worth it yet. - In-app purchases / Play Billing. Separate signing, separate webhooks, doubles the work
(
IAP_GREEN_ENERGY.md§9). Out of scope.
Decisions on record
| # | Decision | Decided by | Date |
|---|---|---|---|
| 1 | Distribution is Play internal testing, not Firebase, not raw APK | Navi4 recommended · Leong accepted | 2026-09-17 |
| 2 | One build number shared across iOS and Android | Leong | 2026-09-17 |
| 3 | No Firebase bridge while the Play account clears — we wait | Leong | 2026-09-17 |
| 4 | One command, sequential iOS then Android, per-store reporting | Navi4 · technical constraint | 2026-09-17 |
| 5 | The keystore is generated and held by Leong only | Pre-existing, 2026-09-09 | 2026-09-09 |
| 6 | Missing key → debug fallback; partial key → hard failure | Pre-existing, 2026-09-09 | 2026-09-09 |
Open questions
| Question | Blocks | Who |
|---|---|---|
| Who has an Android phone for task 1.3? | Phase 1, and therefore everything after it | Leong |
| Does a privacy policy URL already exist? | Task 0.4 | Leong |
Keep com.hoop.hoop or move to a company-domain id? | Task 0.3 — permanent once uploaded | Leong |
Risks, stated plainly
This app has never run on Android. Not once, on any device. The Gradle config is verified
to compile and to select the correct signing path — that is the entire body of evidence. Two Kotlin plugins
(CameraX, ML Kit) have never executed. Treat phase 1 as discovery, not as a formality.
Google sign-in is broken on Android today and the fix depends on a certificate that does not
exist until after the first Play upload. Sequencing matters: task 1.4 cannot move earlier.
Play Console changes and my knowledge has a cutoff. Menu names and the exact set of content
declarations move. Treat the console steps here as the shape of what you will be asked, not a script.
If the Console disagrees with this page, the Console is right and this page is stale.
I have not performed the Play Console or Cloud Console steps myself. Those sections are
written from documentation, not from having clicked through them. Everything about the repo, the iOS pipeline
and the existing Android config was read directly out of
origin/master.The account approval wait is outside anyone's control here. It is the single largest
schedule risk and no amount of preparation shortens it. That is why 0.2 is the first thing to start.