Publishing Android To Play

Publishing Android to Play

Overview

Walks a project from source to a live release on Play's internal testing track, one step at a time, verifying each step before moving to the next.

Core principle: be authoritative where you can verify, advisory where you cannot.

Everything reachable from a shell — the keystore, the signing config, the bundle's own manifest and signature — is a hard gate. Run the check, show the output, refuse to advance on a failure.

Everything inside the Play Console is a browser the agent cannot see. Google renames and reshuffles that UI every few months, so stating click paths as fact produces instructions that are confidently wrong. State the goal, offer today's path as a hint, and ask what the user actually sees.

That inversion is the whole design. A skill that asserts UI it cannot observe ages badly; one that verifies artifacts it can read does not.

When to Use

• "Publish this to the Play Store", "ship an update to my testers", "roll out a new version"
• Setting up release signing or an upload keystore for the first time
• A Play Console upload was rejected and the reason is unclear

Not for: iOS/App Store, production rollout strategy (staged rollouts, A/B testing), Play API automation via service accounts, or driving the Console with a browser tool. This skill deliberately keeps the human in the browser.

Requirements

A Play Console account with the one-time $25 registration paid and identity verification complete. This skill does not cover registration.

The Loop

Phase 0 — Detect (silent, no questions)

Read the project and work out three things before saying anything:

1. Which build path. The test is git, not config sniffing:

git check-ignore -q android/ && echo CNG || echo BARE

android/ ignored → generated and disposable → Expo CNG (references/expo-cng.md). android/ tracked → it is source code → bare RN (references/bare-rn.md).

This test fails safe: an ambiguous project reads as bare, and bare is never regenerated.

2. Identity. Package name, versionCode, versionName, targetSdk.

3. Prior state. Read .play-release.md at the project root if it exists (format below).

Phase 1 — Route

• No .play-release.md, or no app_created → first publish, roughly a dozen steps.
• State exists and the app is live → update rollout, four steps: bump, build, verify, upload.

Do not ask which one. Derive it, then say which you derived and why in one line.

Phase 2 — Step at a time

For each step:

1. State the goal — what must become true, not which button to press.
2. Say who acts. If it is shell work, do it. If it needs a human (a browser, a password, a decision), say what you would choose and why, then wait.
3. Verify. Run the gate. Show its real output, never a summary of it.
4. Record. Update .play-release.md.
5. Advance only on a pass. A failed gate blocks the next step.

Never batch steps. Never present step N+1 while N is unverified.

Hard Gates

Before building

Two of those need explaining.

prebuild --clean deletes android/. If detection is wrong, that destroys hand-written native code. Confirm out loud before running it, every time.

keytool -list proves the keystore/alias/password triple before a four-minute build, instead of surfacing as a Gradle error afterwards. It is also what distinguishes "wrong password" from "typed the store password where the key password was wanted".

After building

./verify.sh <path-to.aab> <project>/.play-release.md

Every gate, exit non-zero on any failure. See verify.sh for what each catches. Show the user its output verbatim — the colour-coded PASS/FAIL lines are the evidence, and paraphrasing them hides which gate fired.

Play Console Steps

Read references/play-console.md. It holds each step as a goal plus a dated hint, and the drift protocol:

If what the user reports does not match the hint, do not improvise a path. Fetch Google's current help page via a Sonnet subagent, re-derive the step, and update the hint's date in the reference file.

Console-side facts the skill states as fact, because they are load-bearing:

• Internal testing is exempt from the 12-testers-for-14-days rule that gates production for personal accounts.
• 100 testers max, added as an email list. They need Google accounts.
• AAB required, not APK. Releases go live in minutes — no review queue.
• The App content dashboard is the authority on which declarations block a rollout. Sources genuinely conflict on whether content rating and target audience gate the internal track specifically. Work the dashboard's list, not a remembered checklist.
• AD_ID does gate internal testing. If the bundle declares it, the advertising ID declaration must be filled in. verify.sh warns when it is present.

State File

.play-release.md at the project root. Gitignore it — add the line if missing. It holds paths and numbers only, never a password, so it stays safe even if the ignore rule is lost.

# play-release state - com.dewill.rentmanager
track: internal
package: com.dewill.rentmanager
keystore: /Users/me/keystores/rent-manager-upload.jks
key_alias: rent-manager
gradle_prefix: RENT_MANAGER
last_uploaded_versionCode: 3
target_sdk_floor: 36
target_sdk_floor_checked: 2026-08-15
perm: android.permission.INTERNET
perm: android.permission.USE_BIOMETRIC
perm: android.permission.VIBRATE

- [x] keystore generated and backed up
- [x] signing wired
- [x] app created in Console
- [x] declarations green (2026-08-15)
- [ ] release 4 uploaded

verify.sh reads package, last_uploaded_versionCode, target_sdk_floor, target_sdk_floor_checked, and the perm: lines. Absent keys downgrade a gate to SKIP rather than inventing a baseline — a first release has no history, and saying so beats guessing.

Update last_uploaded_versionCode only after the user confirms the upload succeeded. Recording it at build time makes a failed upload look shipped, and the next build then gets blocked for no reason.

target_sdk_floor_checked is a real expiry. Google raises the floor annually. Past 180 days verify.sh warns, and the correct response is to look up Play's current requirement, not to trust the stored number.

Keystore Guidance

The location is a stored value, never a convention. What matters:

• Absolute path. Gradle does not expand ~, and a relative path resolves against android/, which CNG deletes.
• Outside the repo. Not "inside but gitignored" — one git add -f, one zip of the project folder, and a signing key is somewhere it cannot be retracted from.
• Backed up off the machine. A cloud-synced folder is a good place: the file is password-protected, and the realistic threat is losing it, not someone stealing it. Keep the password in a password manager, never beside the file.
• Namespaced Gradle properties. ~/.gradle/gradle.properties is global across every app. Two projects both using MYAPP_UPLOAD_STORE_FILE would sign one with the other's key. Derive the prefix from the package name.
• -validity 10000 (~27 years). An expired upload key means a support ticket.

Never write passwords into the project. ~/.gradle/gradle.properties is outside every repo and cannot be committed by accident — unlike android/gradle.properties, which is tracked in bare RN projects and is where most signing tutorials wrongly tell you to put them.

Non-Obvious Failures

Every row cost real time to find.

Verify Before Claiming Success

A build that produced a file is not a release that will be accepted.

• ./verify.sh exits 0, with every gate PASS or a deliberately-understood SKIP
• the signer CN is your key, not CN=Android Debug and not a throwaway
• versionCode is genuinely higher than what is live
• the permission list is what you expect, item by item

Then, before telling the user to upload: has this exact release build ever run on hardware? A release build differs from debug — minification, no dev bundle, real signing. A green gate says the artifact is well-formed, not that the app works. Say so plainly rather than implying the checks cover it.

Files

• verify.sh — the post-build gates; run it, show its output verbatim
• assets/withReleaseSigning.js — Expo config plugin, survives prebuild --clean
• references/expo-cng.md — build path for a gitignored android/
• references/bare-rn.md — build path for a committed android/
• references/play-console.md — Console steps as goals, with dated hints