Skip to content

t1k:marketing:store:play-upload-build

FieldValue
Modulestore
Version0.14.9
Efforthigh
Tools—
/t1k:marketing:store: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.

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:

StepAgent
Run status --package <pkg> and report the track statet1k-metrics-reporter — read-only; the work is running the script and tabulating its output
Run upload ... WITHOUT --confirm and report the validation resultt1k-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).

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.

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.

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 forWhat actually happens
--track internal (default)Your testers only. Safe to iterate on.
--track alpha / betaYour closed testers. Recoverable.
--track production, completedReaches every user now.
--track production, inProgressReaches 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.

A service-account key with per-app grants in Play Console. One-time setup, 15 minutes: references/service-account-setup.md.

Terminal window
set -a; source ~/.config/t1k/ads.env; set +a # exports PLAY_SERVICE_ACCOUNT_JSON

PLAY_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.

Terminal window
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 committed

Read the preview. Then commit it as a saved draft (this is all --confirm does; it never sends for review):

Terminal window
# … same command, plus:
--confirm # commits with changesNotSentForReview=true

Then 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.

Terminal window
# user chose "send for review":
bun <skill>/scripts/play-upload-build.cjs submit --package com.studio.game # preview
bun <skill>/scripts/play-upload-build.cjs submit --package com.studio.game --confirm # sends

User 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:

Terminal window
bun <skill>/scripts/play-upload-build.cjs status --package com.studio.game
bun <skill>/scripts/play-upload-build.cjs status --package com.studio.game --track production

--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.

Terminal window
--track production --status inProgress --user-fraction 0.1 --confirm
Terminal window
--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":"..."}]

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.

references/symbol-files.md has the full detail per build system. In short:

FileGradle / AGPUnity
AABapp/build/outputs/bundle/<variant>/app-<variant>.aabBuild Settings → Build App Bundle
mapping.txtapp/build/outputs/mapping/release/mapping.txtsame (Gradle export)
native symbolsapp/build/outputs/native-debug-symbols/release/native-debug-symbols.zipCreate 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.txt is text.
  • --user-fraction is in (0, 1) and only with inProgress/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-symbols is optional for that build.
  • submit on 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 (submit without --confirm) runs the real open/validate/delete and will show it.

  • versionCode must strictly increase. Re-uploading a code Play has already seen fails with apkUpgradeVersionConflict. 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_grant arrives as HTTP 400, not 401. A revoked or deleted key, or clock drift on this machine — the JWT iat/exp are 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.

  • ackBundleInstallationWarning is 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.

  • references/api-surface.md — every endpoint and limit used, with the verification date
  • references/symbol-files.md — per-build-system paths, ABI layout, the embedded-symbols case
  • references/service-account-setup.md — one-time credential + per-app grant setup
  • rules/ad-network-mcp-write-safety.md — the money/blast-radius guardrail this skill follows
  • rules/preview-first-batch.md — why preview-then-confirm is mandatory, not a nicety