PollyGlot/google-play-cli-skills / skills/gplay-release-flow
gplay-release-flow
VerifiedShip Android releases through Google Play with `gplay releases`. Use when uploading an AAB or APK to a track, promoting a build up the track ladder, steering a staged rollout, inspecting or downloading what a track holds, building a system APK for a device image, attaching a ProGuard/R8 mapping, sharing a build via Internal App Sharing, or managing legacy OBB expansion files.
gplay release flow
Shared conventions are in gplay-cli-usage; onboarding auth is gplay-setup.
Mental model: the track ladder + the rollout state machine
A build is uploaded to one track (internal, alpha, beta,
production, or any custom closed-track name) and then promoted up the
ladder: the same versionCode, no AAB re-upload. On a track, the latest
release moves through a small state machine:
draft ──► inProgress (userFraction f, 0 < f < 1) ──► completed (no fraction)
│ ▲
halt│ │resume
▼ │
halted (fraction preserved)
rollout sets the fraction, halt freezes it, resume un-freezes it, and
complete ramps to 100%. --staged takes a fraction strictly between 0 and
1: --staged 1.0 exits 2 before any call; a full rollout is --complete
(on upload/promote) or releases complete. When a track holds two
releases (e.g. inProgress plus halted), every verb refuses to guess (exit 60): pin one with
--version-code or --release-name.
Upload a build to a track
gplay releases upload ./app.aab --track internal
gplay releases upload ./app.aab --track production --staged 0.1 --confirm
gplay releases upload ./app.aab --track production --complete --confirm
Any string is a valid --track, but the track must already exist (see
Track must exist first below). Flags: gplay releases upload --help.
AAB/APK uploads are resumable: a transient interruption resumes instead of restarting from zero. Automatic, no flag.
upload also takes a legacy .apk ([experimental], same pipeline;
--format apk|bundle overrides an ambiguous extension).
Several artifacts, one release
gplay releases upload phone.aab wear.aab --track beta --retain-version-code 41
Several positional artifacts (per-ABI APKs, a phone plus a Wear bundle) land in
one Edit and one release listing every versionCode, all or nothing: any failure
discards the Edit. --retain-version-code keeps an already-uploaded build
serving alongside them; gplay passes it unchecked, so a wrong code fails with
Google's error. --mapping takes a single artifact: for a multi-artifact
release, attach mappings afterwards with releases mappings upload.
--externally-hosted <file.json> ([experimental]) registers an APK served
from your own host instead of uploading one: Managed Play private apps only
(see gplay-customapps), shape in gplay schema ExternallyHostedApk.
Local preflight
Before any byte leaves, gplay checks the artifact by structure (container
format plus declared package name), whatever its extension says: a mismatch
fails offline with exit 20, no Edit opened. An unreadable manifest degrades
to a stderr NOTE and the upload proceeds. --dry-run reports the result;
--mapping passes unchecked. Same guard on every artifact upload.
Name release-notes files in BCP 47 (en-US.txt): an underscore form
(en_US.txt) is refused before the Edit opens, every offending file in one
error.
Promote a build up the ladder (no re-upload)
gplay releases promote --from internal --to alpha
gplay releases promote --from beta --to production --staged 0.1 --confirm
gplay releases promote --from alpha --to beta --plan # read both tracks, write nothing
The copy replaces every release already on --to, a halted or draft one
included, and the ✓ line names the versionCodes it replaced (gplay 2.5.0+).
--dry-run reads no track, so it cannot name them: run --plan
([experimental], same rules as below) before promoting onto a track that may
hold something. --from equal to --to exits 2 before any call. The
source's countryTargeting carries over to a staged rollout on production
only, the one place Play accepts it.
Release notes are checked before the Edit opens, --dry-run included: an
empty note or one over 500 Unicode characters exits 20 and names the locale.
Same check on releases upload. A default.txt is only checked when it is
actually used.
Staged rollout: rollout / halt / resume / complete
These four act on the latest release of --track.
gplay releases rollout --track production --staged 0.25 --confirm # set fraction → inProgress
gplay releases halt --track production # freeze at current fraction
gplay releases resume --track production --confirm # un-freeze, continue
gplay releases complete --track production --confirm # ramp to 100% → completed
A track holds one completed release at most. complete therefore drops the
previous full rollout in the same update, as the Play Console does, and names
its versionCodes as superseded on the ✓ line (--output json stays the
verbatim tracks.update body). Halted, draft and other inProgress releases
stay untouched; rollout, halt and resume never drop a release.
Read the live track first with --plan
--dry-run stays offline, so it cannot say which release a transition hits or
replaces. --plan ([experimental], on the four verbs above and on
promote) reads the live track and writes nothing: run it before any
production transition, then re-run the same line with --confirm instead of
--plan.
gplay releases complete --track production --plan
gplay releases complete --track production --confirm
- It names the target release, the status and fraction it would end in, and
the releases it would supersede or keep.
--output jsonis gplay-shaped and carries"plan": true, never atracks.updatebody. - No
--confirmneeded. It needs a credential: it reads inside the pinned Edit whengplay edits beginopened one, else in a throwaway Edit it always discards. - An ambiguous track fails with exit
60, as the live call would: add the--version-codeor--release-namethe plan should use, and keep it on the live call. --planwith--dry-runexits2. UnderGPLAY_READONLYit runs, like--dry-run: it reads the live track and writes nothing.
Inspect what is on a track
gplay releases list --track production
gplay releases list --track production --output json
gplay releases list --track production --columns name,status,userFraction
releases list shows every release on one track; cross-track views are
gplay-tracks. releases artifacts list ([experimental]) lists every
APK/AAB attached to the app with the versionCode promote and rollout
accept:
gplay releases artifacts list --format bundle
Generated APKs (what Play signs from your AAB)
generated ([experimental]) lists and downloads the APKs Play signs and
serves from your bundle: verify the signing identity, sideload, archive.
gplay releases generated list --version-code 42
gplay releases generated download <downloadId> --version-code 42 --dest ./universal.apk
Read a fresh Download ID from list each time: it changes across
re-generation. A failed download leaves no partial file.
System APK variants (device system images)
system-apks ([experimental]) asks Play to build an APK for an OEM or
preload system image from an uploaded AAB, then lists, reads and downloads it.
gplay releases system-apks create --version-code 42 --abi arm64-v8a --screen-density 480 --locale en-US --dry-run
gplay releases system-apks list --version-code 42
gplay releases system-apks view <variantId> --version-code 42
gplay releases system-apks download <variantId> --version-code 42 --dest ./system.apk
A direct call outside the Edit lifecycle. create only adds a variant (no
--confirm), and Play assigns the variantId that view and download
take: read it from create or list.
Deobfuscation mappings (symbolicate vitals crash stacks)
# With the artifact, in the same Edit (the common case):
gplay releases upload ./app.aab --track production --mapping ./mapping.txt --confirm
# After the fact, on an already-published versionCode:
gplay releases mappings upload ./mapping.txt --version-code 42
Symbolicated stacks are read in gplay-vitals.
Internal App Sharing (private shareable build links)
gplay releases sharing upload ./app.aab # prints a private downloadUrl
gplay releases sharing upload ./app.aab --dry-run
releases sharing upload ([experimental]) bypasses tracks and the Edit
lifecycle: a private QA link, not a release. No --confirm.
Legacy OBB expansion files
APK-only, legacy. When the task touches .obb files, read obb.md.
Production safety
Production defaults to a draft (ADR-0002): --complete / --staged
there, and rollout, resume and complete on production, reach real users,
so each requires --confirm. halt is exempt: it reaches no new user.
Track must exist first (trackhint)
upload/promote to a custom track that does not exist fails with exit
30 and names the fix: gplay tracks create <name> (see gplay-tracks),
then re-run. Creating a track is always that explicit step; the standard
tracks always exist.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |