From 7a1d99a688dafb2ad27100d66d1c0057fd4dc544 Mon Sep 17 00:00:00 2001 From: Den <2119348+dzianisv@users.noreply.github.com> Date: Sat, 18 Jul 2026 03:04:53 -0700 Subject: [PATCH] docs(publishing): add release runbook + production-promotion gotcha (#118) Captures the proven release flow (bump+changelog -> tag -> internal -> promote) and documents that CI publishes to internal ONLY by design: the service account lacks production scope, so a track=production workflow_dispatch fails with 'The caller does not have permission' after building. Records both the recommended Console promotion (add-from-library, no rebuild) and the optional path to fully-automated prod releases (grant the SA production permission first). Learned the hard way when v0.4.8's production dispatch failed post-build. Claude-Session: https://claude.ai/code/session_01T12AhSnQVrSxNnvwfCx2z6 Co-authored-by: engineer Co-authored-by: Claude Fable 5 --- PUBLISHING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/PUBLISHING.md b/PUBLISHING.md index 05e4dab..200fda6 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -42,6 +42,20 @@ The publish workflow runs on: It builds an AAB (Android App Bundle), signs it with the release keystore, and uploads to the **internal** track. Promote to production via Play Console. +## Releasing (proven runbook) + +1. Bump `version` in `package.json` **and** `app.json`, and `android.versionCode` in `app.json` (must be higher than the current Play build). Add a changelog at `fastlane/metadata/android/en-US/changelogs/.txt`. Merge to `main`. +2. Tag the release: `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z`. This triggers the publish workflow → **internal** track. +3. Verify the publish run is green, then confirm the build on the internal track. +4. **Promote to production** (see below). + +## Promoting to production + +Production is **not** published by CI by default — the service account is scoped to the internal track only, which is intentional (a human gate before a build reaches all users). + +- **Recommended — Play Console:** Production → Create release → **Add from library** → select the `versionCode` already uploaded to internal → review → roll out. No rebuild. +- **Fully automated (optional):** grant the CI service account **"Release to production"** for this app in Play Console → Users & permissions, then run the workflow's `workflow_dispatch` with `track=production`, `status=completed`. **Without that permission the production dispatch fails with `The caller does not have permission` after building** — so don't dispatch `track=production` until the service account has been granted production access. + ## Fastlane (Alternative) A Fastlane setup is included for local publishing: