t1k:marketing:store:play-upload-build
| Field | Value |
|---|---|
| Module | store |
| Version | 0.14.9 |
| Effort | high |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:store:play-upload-buildPlay Upload Build
Section titled “Play Upload Build”Publishes one Android build to one track: the AAB, its deobfuscation mapping, its native debug symbols, and the track assignment — all in a single Play edit, so the four succeed or fail together. A bundle that uploads without its mapping is a stack trace you cannot read six months later, which is why they are one unit here.
Executed by
Section titled “Executed by”Choosing the track and deciding to commit is judgment and stays on a reasoning tier (routing
SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only the read-only runs
of scripts/play-upload-build.cjs are cheap-tier:
| Step | Agent |
|---|---|
Run status --package <pkg> and report the track state | t1k-metrics-reporter — read-only; the work is running the script and tabulating its output |
Run upload ... WITHOUT --confirm and report the validation result | t1k-metrics-reporter — the preview edit is deleted, nothing is committed |
Stays reasoning-tier: picking the track and rollout, locating the right AAB/mapping/symbol files,
and every upload --confirm / submit --confirm (they write to Google Play).
When to use
Section titled “When to use”Activate on: “upload aab”, “upload build to play”, “play upload build”, “upload symbols”, “native debug symbols”, “mapping.txt”, “deobfuscation”, “new build version play”, “google play developer api upload”.
- Uploading a new version → this skill.
- Building the AAB, bumping
versionCode, writing release notes copy → not this skill. - Store listing, graphics, Data Safety, IAP catalog → the Console setup path, not this one.
Manifest mode (the gate path)
Section titled “Manifest mode (the gate path)”With a store manifest the commit follows the same default (a saved draft; only play.release.sendForReview: true sends for review, noReview is a deprecated no-op). The upload is a step of ONE command, bun ../t1k-marketing-store-play-console-setup/scripts/play-console-setup.cjs store --manifest <m>:
the AAB, mapping and native symbols come from play.release.aab, mapping and nativeSymbols, the package from
stores.play.packageName, and the track, status, rollout fraction, release notes, noReview and cancelInReview
from the other play.release fields. It reuses this script’s local pre-checks (validateUpload, preflightFiles),
reads each file once into a buffer, hashes it (artifactSha256 in the diff), uploads that buffer and compares
Play’s reported sha256. upload, status and submit here exit 2 under --manifest (“use store”); without --manifest
this script is unchanged. Exit codes: 0 ok, 1 error, 2 usage (a bad flag, an invalid --package). Migration note: a usage error exited 1 before the
store module moved this script; it is 2 now, so a wrapper that tested $? -eq 1 for a bad flag must test 2.
Blast radius — read before --confirm
Section titled “Blast radius — read before --confirm”This skill can put a build in front of real users. It is the Play-side twin of
rules/ad-network-mcp-write-safety.md: one app at a time, never a loop over an account,
and never a write you have not previewed.
| What you asked for | What actually happens |
|---|---|
--track internal (default) | Your testers only. Safe to iterate on. |
--track alpha / beta | Your closed testers. Recoverable. |
--track production, completed | Reaches every user now. |
--track production, inProgress | Reaches that fraction of users now. |
Halting is not a rollback. --status halted stops the rollout; it neither uninstalls the
build nor reverts anything. A build at 100 % on production cannot be un-shipped.
Preview first, always. Every destructive path here is gated behind --confirm, per
rules/preview-first-batch.md — smoke the real thing, read the output, then confirm. Without
--confirm nothing is committed: the script opens a real edit, uploads, assigns the track, runs
Google’s edits.validate, then deletes the edit. The preview is not an approximation — what
validates in preview is what commits.
Prerequisite — credentials
Section titled “Prerequisite — credentials”A service-account key with per-app grants in Play Console. One-time setup, 15 minutes:
references/service-account-setup.md.
set -a; source ~/.config/t1k/ads.env; set +a # exports PLAY_SERVICE_ACCOUNT_JSONPLAY_SERVICE_ACCOUNT_JSON is the absolute path to the key JSON — never its contents. The
key is a private key in cleartext: it never belongs in the repo, a CI log, or a chat message.
The script prints the path, never the key.
Workflow
Section titled “Workflow”bun <skill>/scripts/play-upload-build.cjs upload \ --package com.studio.game \ --aab app/build/outputs/bundle/release/app-release.aab \ --mapping app/build/outputs/mapping/release/mapping.txt \ --native-symbols app/build/outputs/native-debug-symbols/release/native-debug-symbols.zip \ --track internal # preview — nothing committedRead the preview. Then commit it as a saved draft (this is all --confirm does; it never sends
for review):
# … same command, plus: --confirm # commits with changesNotSentForReview=trueThen STOP and ask the user (AskUserQuestion: send for review | stop). Never send for
review on your own, and never infer the answer from an earlier “go ahead” to upload. A Play commit
is never sent for review straight away, for any track change: upload, staged rollout, track move.
# user chose "send for review":bun <skill>/scripts/play-upload-build.cjs submit --package com.studio.game # previewbun <skill>/scripts/play-upload-build.cjs submit --package com.studio.game --confirm # sendsUser chose “stop”: leave the draft or discard it. The Android Publisher API has no call that
discards a committed draft (edits.delete only removes an uncommitted edit), so discarding means
Play Console → Publishing overview → Changes not yet sent for review → discard. Say so; do not
pretend the script can undo it.
Check what is live at any time — read-only, opens an edit, deletes it, commits nothing:
bun <skill>/scripts/play-upload-build.cjs status --package com.studio.gamebun <skill>/scripts/play-upload-build.cjs status --package com.studio.game --track productionStaged rollout
Section titled “Staged rollout”--user-fraction is only legal with --status inProgress or halted. Play rejects a fraction
on a completed release at commit time — after the upload has already happened — so the
script refuses it locally instead of wasting the upload.
--track production --status inProgress --user-fraction 0.1 --confirmRelease notes
Section titled “Release notes” --release-notes 'en-US=New levels and a fixed crash on low-end devices;vi-VN=Màn chơi mới' --release-notes notes.json # {"en-US":"..."} or [{"language":"en-US","text":"..."}]Sending for review
Section titled “Sending for review”A commit never sends for review by default: it saves a draft (changesNotSentForReview=true),
which Play adds to any other change not yet sent. submit --package <pkg> --confirm opens an edit
with no changes of its own and commits it WITHOUT that parameter, which sends the whole pending
draft for review (so it also sends drafts someone else left in the Console; read the Console’s
“Changes not yet sent” list first). Without --confirm it validates then deletes the edit.
upload --send-for-review is the one-step form, for when the user has already said so for this
exact change; the agent does not choose it unprompted. --no-review is a deprecated no-op alias
(draft is the default) and prints a warning.
--cancel-in-review is destructive and opt-in: it sets
changesInReviewBehavior=CANCEL_IN_REVIEW_AND_SUBMIT, which silently cancels any in-flight
review of this app. The default is ERROR_IF_IN_REVIEW — the commit fails instead, which is
the only safe default. Do not add this flag to make an error go away.
Where the files come from
Section titled “Where the files come from”references/symbol-files.md has the full detail per build system. In short:
| File | Gradle / AGP | Unity |
|---|---|---|
| AAB | app/build/outputs/bundle/<variant>/app-<variant>.aab | Build Settings → Build App Bundle |
mapping.txt | app/build/outputs/mapping/release/mapping.txt | same (Gradle export) |
| native symbols | app/build/outputs/native-debug-symbols/release/native-debug-symbols.zip | Create symbols.zip → <name>-<version>-v<code>.symbols.zip |
What the script checks locally, before any network call
Section titled “What the script checks locally, before any network call”All of these run before a single byte is uploaded:
- The AAB exists and is a zip (PK header); same for the symbols zip;
mapping.txtis text. --user-fractionis in(0, 1)and only withinProgress/halted.- The symbols zip has per-ABI directories at the zip root (
arm64-v8a/,armeabi-v7a/,x86_64/…). A wrapper directory is the usual reason a valid-looking zip is rejected server-side; the script warns by name. - The AAB embeds
BUNDLE-METADATA/com.android.tools.build.debugsymbols→ AGP already shipped the native symbols inside the bundle and--native-symbolsis optional for that build.
Hard rules
Section titled “Hard rules”-
submiton an app with no pending draft is unverified. Whether Play accepts an empty-edit commit (versus a “no changes” error) has not been exercised against a live app; the preview (submitwithout--confirm) runs the real open/validate/delete and will show it. -
versionCodemust strictly increase. Re-uploading a code Play has already seen fails withapkUpgradeVersionConflict. Bump it (android.defaultConfig.versionCode, or the Unity bundle version code) and rebuild — do not retry. -
The commit fails if the Console holds an uncommitted draft. Play allows one open edit per app; a draft someone left open in the web UI blocks the commit. Open the Console, publish or discard it, then re-run.
-
invalid_grantarrives as HTTP 400, not 401. A revoked or deleted key, or clock drift on this machine — the JWTiat/expare absolute. Check NTP first; it is the cheaper fix. -
A brand-new app cannot be created by this API. There is no “create app” endpoint — the app record is made in the Console. The very first bundle for an app may likewise need a manual upload before the API accepts one. Treat the first release of a new title as a Console step, not as a failure of this script.
-
The
apks/path segment is not a typo. Symbol files upload under.../edits/{id}/apks/{versionCode}/deobfuscationFiles/{type}even though the version code came from an AAB. That is the Android Publisher v3 shape. -
ackBundleInstallationWarningis deprecated. The script does not send it. -
403 immediately after granting permissions is propagation, not a misconfiguration. It genuinely takes a few minutes.
-
One edit per app. Two people uploading to the same package at once will collide; the second commit fails. Serialise uploads per app.
Related
Section titled “Related”references/api-surface.md— every endpoint and limit used, with the verification datereferences/symbol-files.md— per-build-system paths, ABI layout, the embedded-symbols casereferences/service-account-setup.md— one-time credential + per-app grant setuprules/ad-network-mcp-write-safety.md— the money/blast-radius guardrail this skill followsrules/preview-first-batch.md— why preview-then-confirm is mandatory, not a nicety