opencode-mobile/PUBLISHING.md

Publishing to Google Play Store

Required GitHub Secrets

Configure these in Settings > Secrets and variables > Actions:

Secret	Description
PLAY_STORE_SERVICE_ACCOUNT_JSON	Google Play Console service account JSON key (full JSON content)
KEYSTORE_BASE64	Base64-encoded release keystore (base64 -w0 release.keystore)
KEYSTORE_PASSWORD	Keystore password
KEY_ALIAS	Key alias in the keystore
KEY_PASSWORD	Key password

Setup Steps

1. Create a release keystore

keytool -genkeypair -v -storetype PKCS12 \
  -keystore release.keystore -alias release \
  -keyalg RSA -keysize 2048 -validity 10000

Encode it for GitHub secrets:

base64 -w0 release.keystore

2. Create a Google Play service account

1. Go to Google Cloud Console > IAM > Service Accounts
2. Create a service account and download the JSON key
3. In Google Play Console > Settings > API access, link the service account
4. Grant it release management permissions for your app

3. Workflow triggers

The publish workflow runs on:

• GitHub Release publish events
• Tag pushes matching v*

It builds an AAB (Android App Bundle), signs it with the release keystore, and uploads to the production track (status: completed). Manual workflow_dispatch runs still honour the track/status inputs and default to internal.

Releasing (proven runbook)

1. Bump the version in four places, then run npm run check:versions before you push: package.json version, app.json expo.version, and android/app/build.gradle versionName — plus versionCode in both app.json (expo.android.versionCode) and build.gradle, incremented by one.
   • Play does not need the hand-bumped versionCode (the publish workflow overrides it with github.run_number + 100, so the Play code is e.g. 152, unrelated to the app.json number). F-Droid and direct-APK installs do. They key upgrades off versionCode, so a release that reuses the previous one is silently never offered to anyone who already has that code installed. v0.4.15 shipped with v0.4.14's versionCode 41 for exactly this reason (fixed in #180) — the F-Droid publish failed outright and the GitHub release never got created.
2. Add the changelog for the new versionCode in both distribution/changelogs/<versionCode>.txt and fastlane/metadata/android/en-US/changelogs/<versionCode>.txt (F-Droid reads the fastlane copy), and update the Play release notes in distribution/whatsnew/whatsnew-en-US (single file, applied to the build being uploaded; max 500 chars). whatsnew — not the fastlane changelogs/*.txt — is what the Play publish uses (whatsNewDirectory in the workflow). check:versions enforces that the changelog named after the versionCode describes the version you are releasing. Merge to main.
3. Tag the release: git tag -a vX.Y.Z <sha> -m "..." && git push origin vX.Y.Z. This triggers the publish workflow → production track, status: completed.
4. Verify the publish run is green, and read the run summary — it records the event, resolved track/status, and the real Play versionCode (run_number+100, not the app.json number).
5. Check the other two channels, because Play is only one of three and the smaller share of the install base: the GitHub release exists with both APKs (build.yml's release job — this is what the in-app update check polls via releases/latest), and the F-Droid index lists the new version (https://dzianisv.github.io/opencode-mobile/fdroid/repo/index-v1.json).
6. Nothing else to do. There is no second promotion step.

Promoting to production

CI does this for you on every release tag (AGE-110). The service account does hold "Release to production" — verified by run 31807432647 (Validating tracks: 'production' → committed edit 02632873494323676310, 2026-08-14 14:22 UTC), so the older "internal only" note here was stale.

Manual paths, still available when you need them:

• Recommended — Play Console: Production → Create release → Add from library → select the build by its versionName (e.g. 0.4.10) and confirm its versionCode (the run_number-derived one, e.g. 142 — not the app.json number) → review → roll out. If the "What's new" field is empty, paste from distribution/whatsnew/whatsnew-en-US. No rebuild.
• Fully automated (optional): workflow_dispatch with track=production, status=completed — same thing the tag push does, useful for re-shipping main without cutting a tag.

Resubmitting after a Data Safety rejection (issue #143)

Google Play rejected cc.agentlabs.opencode on 2026-07-22 because the app's Data Safety declaration did not disclose collection of Email Address. Root cause: the "OpenCode Connect" waitlist card on the Connect screen (app/connection/add.tsx → src/lib/waitlist.ts → POST https://opencode.agentlabs.cc/api/beta-signup) collects an email address when a user opts in, and the backend forwards it to Brevo (email marketing/CRM). This was true collection that the Data Safety form did not declare — Play requires all personal-info collection to be declared, even when it's optional and unrelated to the app's core function.

The repo-side declaration is now fixed (this PR): distribution/play-listing.md Data Safety table, distribution/privacy-policy.md/.html, and docs/privacy/index.html all disclose the email collection. To resubmit:

1. Play Console → your app → App content → Data safety → Manage.
2. Under Data types → Personal info, check Email address.
   • Is this data collected, shared, or both? → Collected and shared.
   • Is this data processed ephemerally? → No.
   • Is data collection required for your app, or can users choose whether this data is collected? → Users can choose whether this data is collected (optional — only collected if the user opts into the waitlist).
   • Why is this user data collected? → check Account management (the waitlist is a signup for the not-yet-launched hosted service). Optionally also check App functionality if Console requires at least one additional purpose.
   • Under sharing: declare it is shared with a third party (Brevo) for the same purpose.
3. Re-verify the existing declared types are still accurate (unchanged by this fix): App activity (PostHog analytics), App info and performance / Crash logs (Sentry), and Diagnostics — user-submitted reports (Chatwoot) — all opt-in, default OFF, shared with the named third parties. See the full table in distribution/play-listing.md → "Data safety form".
4. Confirm the Privacy policy URL field still points at https://dzianisv.github.io/opencode-mobile/privacy/ (now updated with the email disclosure — docs/privacy/index.html, mirrored from distribution/privacy-policy.md).
5. Save, then Send for review (Play re-reviews Data Safety changes; this is separate from a binary/release review since no code changed).
6. Once Data Safety is approved, resume any blocked release rollout (e.g. 0.4.12 and pending retention fixes) — those builds themselves did not need to change, only the Console-side declaration.

Known earlier blocker (if it resurfaces): a prior release (v0.4.5) was blocked by Google with a "Missing sign-in details" rejection under App access, not Data Safety — Play reviewers could not exercise the app because it requires the user's own opencode server and Play had no way to sign in / connect one. That was resolved (see HANDOFF.md) by providing reviewer instructions plus a temporary demo server URL in the App access form (see the reviewer-instructions block in distribution/play-listing.md → "App access"). If a future review flags "sign-in details" again, the fix is the same: confirm App access still has either working temporary credentials/demo server or an accurate "all functionality available without sign-in" declaration — this is unrelated to the Data Safety fix in this PR, but is the other known rejection mode for this app and worth checking in the same Console pass.

Fastlane (Alternative)

A Fastlane setup is included for local publishing:

bundle install
bundle exec fastlane android deploy

Set environment variables: SUPPLY_JSON_KEY, RELEASE_STORE_FILE, RELEASE_STORE_PASSWORD, RELEASE_KEY_ALIAS, RELEASE_KEY_PASSWORD.