--- name: suede-play-release description: "Suede AI Google Play Release Skills. Google Play release delivery with AAB preflight, test-track upload, exact versionCode promotion, staged rollout, locale notes, and API readback. Use when asked \"promote this Android build\" or to diagnose Play publishing access and prove the served release. NOT FOR: app building or policy review (android-app-factory), listing assets (suede-aso), or CI gates (suede-ci-gate)." metadata: display-name: "Suede AI Google Play Release Skills" --- # Suede AI Google Play Release Skills ## Compatibility Requires Android release artifacts and authorized Google Play publishing access. Bundled preflight uses Python with pyjwt/cryptography and macOS Keychain; delivery examples use fastlane supply. Linux CI uses its secret store. Use [the worked contract](references/worked-contract.md) for a staged rollout example, access-failure recovery, and API readback validation. ```text Iron Law: the Play API decides what shipped, not a green fastlane summary. Every claim about a live release is a readback or it is a guess. ``` ## Gate policy: advisory, not blocking Run every check and report results honestly. Verdicts are advice attached to the work, never a control that changes it. A failed check changes what you report, never what you do. The one exception is the production halt in Step 7: a public release is irreversible for the users who get it, so present the options and let the user pick. ## Step 0: Preflight the credential before anything else Never assume publishing works. Prove it with a real API call that changes nothing: open an edit and delete it. The script reads the key from the macOS login Keychain and needs `pyjwt` and `cryptography`; on Linux CI, load the same base64 JSON from the CI secret store and run the equivalent token exchange. ```bash python3 scripts/play-preflight.py [--service NAME] [--account NAME] ``` Three outcomes, three different actions: | Result | Meaning | Do | | --- | --- | --- | | token fails | key is wrong or revoked | rotate, see Step 1 | | HTTP 401/403 on the edit | Play Console has not granted the account | Step 1's grant | | edit opens and deletes | publishing is wired | continue | A 403 here is the normal state of a brand-new service account, not a bug. ## Step 1: Credentials Use a **dedicated publishing service account**, separate from any billing or purchase-verification account. A credential that can push releases should not also be able to void purchases. Give it no cloud IAM roles: all of its authority comes from the Play Console grant, so before that grant the key is inert. Store the JSON in the login Keychain **base64-encoded**: ```bash security add-generic-password -U -s GOOGLE_PLAY_SERVICE_ACCOUNT_JSON -a -w ``` Run it with `-w` last and no value so it prompts and the key never enters shell history. Paste the base64, not the raw JSON. Base64 is load-bearing. `security` hex-encodes any multi-line secret on read, so raw JSON comes back in one of two shapes depending on content. Base64 gives one shape and one decode path. Granting access is a **Play Console UI action** and cannot be done from the API: invite the service-account email under Users and permissions with release permissions on the app. Report this to the user as a step only they can take, with the exact email and permissions, then re-run Step 0. ## Step 2: Pull before every command `fastlane` reads the working tree, not the remote. A stale checkout produces a run that succeeds and does nothing, because a missing changelog is a skip rather than an error. ```bash git -C pull --ff-only && git -C log --oneline -1 ``` If fastlane offers to set itself up, the Fastfile is not on disk. Answer no and pull; accepting scaffolds an empty config over the real one. ## Step 3: Write the changelog first Release notes live at `fastlane/metadata/android//changelogs/.txt`, one file per locale per versionCode. A missing file is **not** an error. Play silently serves the previous version's notes, so users read stale text against a new build and nothing tells you. Write one for every locale that has listing copy, before uploading. ```bash for l in $(ls fastlane/metadata/android); do [ -f "fastlane/metadata/android/$l/changelogs/$VC.txt" ] || echo "MISSING: $l" done ``` Match each locale's existing register rather than translating the English word for word. Check the limit: 500 characters. ## Step 4: Verify the artifact, never the source tree A source read is not evidence that a change reached the binary. ```bash jarsigner -verify app/build/outputs/bundle/release/app-release.aab | head -1 grep -oE 'android:version(Code|Name)="[^"]*"' \ app/build/intermediates/merged_manifests/release/*/AndroidManifest.xml ``` When the release changes an asset, hash it on both sides and require a match: ```bash unzip -p 'base/res/*xxxhdpi*ic_launcher.png' | shasum -a 256 shasum -a 256 app/src/main/res/mipmap-xxxhdpi/ic_launcher.png ``` `jarsigner` reporting a self-signed certificate is correct under Play App Signing, which re-signs with the real release key. ## Step 5: Upload to a testing track first ```bash fastlane android internal ``` Build uploads carry the binary and its changelogs only. Listing text, icon, feature graphic and screenshots move through a separate lane, so a routine upload cannot rewrite what the store says about the app. ## Step 6: Promote, never re-upload Play rejects a second bundle carrying a versionCode it already has. Re-uploading is not a slower path to the same place, it is an error. Promote the versionCode already on the testing track, which is also the only thing that makes testing-first mean anything: the artifact reaching production is the one that was validated, bit for bit. ```ruby upload_to_play_store( version_code: , track: "internal", track_promote_to: "production", skip_upload_aab: true, skip_upload_apk: true, release_status: "inProgress", rollout: "0.1" ) ``` ## Step 7: Production halt A production rollout is irreversible for the users who receive it. Stop and present: ```text Ready to promote versionCode () to production at % of users. Currently live: versionCode . . 1. Promote at % 2. Promote at a different fraction 3. Upload to a testing track only 4. Hold ``` Then wait. Proceed on an explicit answer, and treat a standing instruction to ship as that answer. ## Step 8: Read back what is actually live The fastlane summary reports that the request succeeded, not what the release became. Parameters like `track_promote_release_status` can differ from the `release_status` you set, so read the track: ``` GET /androidpublisher/v3/applications//edits//tracks/production ``` Check three fields and say them plainly: - `versionCodes`: the build users get. - `status`: `inProgress` is a staged rollout; `completed` is everyone. - `userFraction`: absent when `completed`. A 100% rollout should land as `status: completed` with **no** `userFraction`. A release sitting at `inProgress` with `userFraction: 1.0` is a different state that reads the same in a success message. Confirm which one you got. Also confirm every locale you wrote appears in that release's `releaseNotes`. ## Done means Every line proven by a command in this run: - Preflight opened and deleted a real Play edit. - The AAB verified: signature, versionCode in the merged manifest, and a hash match for any changed asset. - The track readback shows the expected versionCode, status, and fraction. - Every locale with listing copy appears in the live release's notes. ## Boundaries 1. Do not promote to production, raise a rollout, or halt one without an explicit instruction covering that action. 2. Do not create the Play Console grant yourself; it is a UI action. Name the email and permissions and hand it to the user. 3. Do not print, commit, or copy the service-account JSON, the upload keystore, or `keystore.properties` into a repo. 4. Do not push listing text, images, or screenshots as part of a build upload. Store copy moves in its own deliberate step. 5. Do not report a release state from a fastlane summary. Read the track. 6. Do not reuse a billing or purchase-verification service account for publishing. 7. Do not edit a changelog for a versionCode already serving users to fix a typo silently; that changes live store copy and belongs in the same confirmation as a rollout change. ## Routing - Need to plan, build, test, or policy-check the app itself -> use `android-app-factory`, then return here for delivery. - Need listing text, keywords, screenshots, or ratings work -> use `suede-aso`. Listing changes travel in their own deliberate step (Boundary 4), so plan them there and ship them separately from the binary. - Need CI wiring, required checks, or merge gates around the release -> use `suede-ci-gate`. - Need branch, worktree, or stale-mirror handling for the release branch, or the iOS half of the same release -> private Suede AI companions, not in this pack. - Need constants to match across the Android, iOS and web surfaces -> use `suede-parity-contract`. - From `android-app-factory`: route Play credential setup, upload, track promotion, staged rollout, and live-state verification back here.