storebound/skills/play-first-release/SKILL.md

name

description

play-first-release

Step-by-step first (and later) Google Play release of a mobile app or game - Play Console app creation, service account + API access, signing, AAB upload to internal testing, store listing, graphics, data safety, App content declarations, production draft and sending for review. Use when the user wants to publish, release, upload or set up an Android app or game on Google Play, push a Play listing or AAB, or hits Play Developer API errors (edits, "outside of this Edit", draft app releases).

Google Play: first release

The CLI is storebound (on PATH while the plugin is enabled; otherwise bunx storebound in a project that has it, or bun <toolchain>/cli/index.ts; agents can also use the storebound mcp tools). It reads storebound.config.ts in the project (create with storebound init) and credentials from env or .storebound/credentials.json (gitignored). Every write command has --dry. Run storebound check first.

Ask the owner before anything public or irreversible: production releases, "Send for review", publishing, deleting products. Sending a first release for review is the owner's action in the Console, not yours.

Steps (API = storebound does it, UI = Play Console by hand)

1. UI · Create the app. storebound console plan play-app-record (then drive the form with your browser tool, or the scripted storebound console fill play-app-record). The form is /console/u/0/developers/<developerId>/create-new-app: App name (max 30), App package name (play.packageName, max 150; press the read-only "Check availability": "Package name available"; fixed for good), default language, App or Game and Free or Paid (material radios: click the inner [role=radio], then no "Select …" hint may be left), and the declarations, which the owner ticks before pressing Create app. Free can never become Paid. storebound console verify play-app-record checks the form first. Afterwards the app lives at /console/u/0/developers/<developerId>/app/<appId>/app-dashboard: put that app id in play.appId (the App content forms deep-link from it). Owner step after every Create app: a service account's app-level permissions do NOT cover apps created later. The owner opens Users and permissions > the service account > Add app > the new app > Admin (or at least: view app information, manage store presence, release to testing tracks, manage testing tracks, manage production releases, manage policy declarations, manage orders and subscriptions) > Apply > Save changes. Never do this yourself: it is a permission grant (agents in auto mode are blocked from it too). Then storebound apps check --store play.
2. UI · API access. Google Cloud project (any) > enable "Google Play Android Developer API" > create a service account > JSON key (keep it outside the repo). Play Console > Users and permissions > Invite new users > the service account email > app permissions: view app information, manage store presence, release to testing tracks, manage testing tracks, release to production (only if you want API production drafts), manage orders (for purchase checks). Put the key path in PLAY_SERVICE_ACCOUNT. Permissions can take a few minutes to apply.
3. Local · Signing. Generate an upload key (keytool -genkeypair -v -storetype PKCS12 -keystore upload.p12 -alias upload -keyalg RSA -keysize 4096 -validity 10950), keep keystore + passwords out of git and back them up (encrypted, two places). Play App Signing holds the real app key; a lost upload key can be reset via the Console. Check the AAB signer before uploading: keytool -printcert -jarfile app-release.aab. Put the keystore path and passwords in ANDROID_KEYSTORE, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, ANDROID_KEY_PASSWORD (env or .storebound/credentials.json) and storebound play build signs with it (build-and-sign skill).
4. Local · Version. versionName (e.g. 1.0.0) and a versionCode that always increases (storebound play next-version-code prints the next free one; use exactly that code in later steps). storebound play build --version-name 1.0.0 --dry, then without --dry: Gradle bundleRelease (Flutter: flutter build appbundle) with the next free versionCode, AAB in build/android/. Capacitor, React Native, Flutter and Unity exports are found automatically.
5. UI or API · First upload. The very first AAB may need the Console (Testing > Internal testing > Create new release) so Play links the package name; after that: storebound play upload --track internal --dry, then without --dry (asks first; play release app-release.aab does the same with more track options). Add testers (internal testing list) and license testers (Settings > License testing) so test purchases are free.
6. API · Listing text. Fill store/listing.md (one section per language), then storebound play listing. It also sets contact email + website (website = the domain serving app-ads.txt). Run --dry first and show the owner the plan (details and per language old -> new per field; draft languages skipped until listing reviewed, --include-drafts only on the owner's word); the real run asks in a terminal and PUTs only what changes.
7. API · Graphics. Render (store-screenshots skill), storebound shots jpeg, then storebound play images > .storebound/play-images.log 2>&1 & and follow the log (it is slow: one edit per language). Required: the 512 x 512 icon, the 1024 x 500 feature graphic and at least 2 phone screenshots (Play Console Help answer 9866151). 7" / 10" tablet screenshots are optional (no tablet featuring without them): a phone-only project gets an info line, not an error; play.tablets: true renders and requires them, false never asks. Tablet screenshots already on Play stay unless the owner runs --prune.
8. API · In-app products. store-iap-setup skill (storebound play products). Needs a build with the BILLING permission on any track first.
9. API · Data safety. Answers in dataSafety of the config, storebound play data-safety, then check the summary in Policy and programs > App content > Data safety.
10. UI · App content. store-declarations skill: privacy policy, ads, app access, content rating (IARC), target audience, advertising ID, government / financial / health / news, data safety review. Behind a sign-in: App access with the demo account (review-access); with accounts: the delete-account URL (account-deletion); subscriptions: storebound play subscriptions (store-subscriptions).
11. UI · Store settings. Category + tags, contact details.
12. API + UI · Production. storebound play release --version-code N --production draft, then in the Console: Production > Countries/regions > Add countries > select all > Save; Production > the draft release > Edit > Next > Save; Publishing overview > Send changes for review (owner).
13. Verify. storebound validate --play (no blockers), storebound play status (tracks, listings, products), Console dashboard has no open tasks, Publishing overview shows "In review".

Gotchas

• Updates after the first release: staged rollout with release-management (play rollout).

• Draft app: until the first release is reviewed, the API only accepts status: draft ("Only releases with status draft may be created on draft app"). Create the production draft via API, finish in the Console (step 12).

• "A change was made to the application outside of this Edit": any Console save or other edit commit invalidates an open API edit. storebound redoes the edit automatically (3 retries) and uses one edit per language for images, but do not save things in the Console while uploads run.

• Uploads (AAB, 100+ images) take minutes: run them in the background with a log file and watch progress lines.

• Personal developer accounts created after 2023-11-13 need a closed test with at least 12 opted-in testers for 14 days in a row before they can apply for production (Play Console Help answer/14151465); organization accounts skip that rule. Set play.accountType and play.accountCreated so storebound scan reminds you.

• 16 KB page sizes: apps with native code (Unity, Flutter, React Native, NDK) must support 16 KB pages; from 2027-02-01 Play blocks updates that don't. storebound scan flags old Unity / React Native / NDK / AGP versions and lists prebuilt .so files; check the built app with zipalign -v -c -P 16 4 app.apk.

• Phone screenshots: 2-8, sides 320-3840 px, long side at most 2x the short side (1080 x 1920 fine, 1080 x 2400 not). Feature graphic 1024 x 500 required. PNG without alpha, or JPEG (q92 is 4x smaller and uploads faster).

• Play listing limits: title 30, short 80, full 4000, release notes 500 (checked locally before upload).

• The legacy inappproducts API returns 403 "Please migrate to the new publishing API": use monetization.onetimeproducts (what storebound play products does).

• Wrong path casing on the new product endpoints returns an HTML 404, not JSON (oneTimeProducts camelCase for list and batchUpdateStates).

• Website in the listing must be the exact domain whose /app-ads.txt lists your ad networks.