gplay-release-flow

name	gplay-release-flow
description	End-to-end release workflows for Google Play tracks (internal, beta, production) using gplay release, promote, and rollout commands. Use when asked to upload a build, distribute to testers, or release to production.

Release flow (Internal, Beta, Production)

Use this skill when you need to get a new build onto Google Play Store.

Preconditions

• Ensure credentials are set (gplay auth login or GPLAY_SERVICE_ACCOUNT env var).
• Build must be an AAB (App Bundle) or APK.
• Version code must be higher than previous releases.
• Service account needs "Release Manager" permission in Play Console.

Android Release

Preferred end-to-end commands

Internal track (for internal testing):

gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab

Beta track (for beta testers):

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --release-notes @release-notes.json

Production with staged rollout (gradual release):

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --rollout 0.1

Dry run (preview the release without executing):

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --dry-run

Release with metadata (listings and screenshots)

Include store listings from a directory:

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata

Skip metadata or screenshots:

# Upload bundle only, skip metadata sync
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --skip-metadata

# Upload bundle and metadata, skip screenshots
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --skip-screenshots

Combine listings and screenshots directories:

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --listings-dir ./metadata/listings \
  --screenshots-dir ./metadata/images \
  --release-notes @release-notes.json

Manual sequence (when you need more control)

1. Create edit session:

   EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
   

2. Upload bundle:

   gplay bundles upload \
     --package com.example.app \
     --edit $EDIT_ID \
     --file app-release.aab
   

3. Update track:

   gplay tracks update \
     --package com.example.app \
     --edit $EDIT_ID \
     --track production \
     --releases @releases.json
   

   --releases takes a JSON array of track releases (or @file).

4. Validate edit:

   gplay edits validate --package com.example.app --edit $EDIT_ID
   

5. Commit edit (publishes changes):

   gplay edits commit --package com.example.app --edit $EDIT_ID
   

Track Promotion

Promote a release from one track to another:

# Promote from internal to beta
gplay promote \
  --package com.example.app \
  --from internal \
  --to beta

# Promote from beta to production with 25% rollout
gplay promote \
  --package com.example.app \
  --from beta \
  --to production \
  --rollout 0.25

Staged Rollout Management

Start with a 10% rollout (fraction 0.1):

gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --rollout 0.1

Increase to 50% (fraction 0.5):

gplay rollout update \
  --package com.example.app \
  --track production \
  --rollout 0.5

Halt rollout (pause distribution):

gplay rollout halt --package com.example.app --track production

Resume rollout:

gplay rollout resume --package com.example.app --track production

Complete rollout (release to 100%):

gplay rollout complete --package com.example.app --track production

Release Notes Format

The single --release-notes flag accepts three shapes: a JSON array (multi-locale), plain text (auto-assigned to en-US), or an @file path pointing to either. There is no separate locale flag.

JSON array format (multi-locale)

release-notes.json — a JSON array of {language, text} entries:

[
  { "language": "en-US", "text": "Bug fixes and performance improvements" },
  { "language": "es-ES", "text": "Correcciones de errores y mejoras de rendimiento" },
  { "language": "fr-FR", "text": "Corrections de bugs et améliorations des performances" }
]

Pass it with --release-notes @release-notes.json.

Plain text format (single locale)

Provide release notes as plain text — it is auto-assigned to en-US:

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes "Bug fixes and performance improvements"

Or from a file (plain text or a JSON array) with @:

gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes @release-notes.txt

Release Flags Reference

Flag	Description
--package	App package name (required)
--track	Target track (production, beta, alpha, internal; default: internal)
--bundle	Path to AAB file (use --bundle or --apk, not both)
--apk	Path to APK file (alternative to --bundle)
--release-notes	Release notes: plain text (auto-assigned en-US), a JSON array of {language, text}, or @file
--rollout	Staged rollout fraction (0.0-1.0, default: 1.0 for full rollout)
--listings-dir	Directory containing store listings to sync
--screenshots-dir	Directory containing screenshots to upload
--skip-metadata	Skip metadata/listings sync during release
--skip-screenshots	Skip screenshots upload during release
--dry-run	Preview the release without executing
--output	Output format (json, table, markdown)

Pre-release Checklist

Before releasing, verify:

• Version code is incremented
• AAB/APK is signed with correct keystore
• ProGuard/R8 mapping files uploaded (for crash reports)
• Release notes written for all locales
• Testing completed on internal/beta track
• Service account has correct permissions
• Dry run passes: gplay release ... --dry-run

Common Release Strategies

Strategy 1: Internal -> Beta -> Production

# Week 1: Internal
gplay release --package com.example.app --track internal --bundle app.aab

# Week 2: Beta (after testing)
gplay promote --package com.example.app --from internal --to beta

# Week 3: Production with staged rollout
gplay promote --package com.example.app --from beta --to production --rollout 0.1
gplay rollout update --package com.example.app --track production --rollout 0.5  # Day 2
gplay rollout complete --package com.example.app --track production             # Day 7

Strategy 2: Direct to Production with Staged Rollout

# Day 1: 10%
gplay release --package com.example.app --track production --bundle app.aab --rollout 0.1

# Day 2: 25%
gplay rollout update --package com.example.app --track production --rollout 0.25

# Day 3: 50%
gplay rollout update --package com.example.app --track production --rollout 0.5

# Day 7: 100%
gplay rollout complete --package com.example.app --track production

Strategy 3: Full release with metadata and dry-run verification

# 1. Dry run to verify everything
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata \
  --release-notes @release-notes.json \
  --rollout 0.1 \
  --dry-run

# 2. Execute the release
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata \
  --release-notes @release-notes.json \
  --rollout 0.1

Notes

• Always use --help to verify flags for the exact command.
• Use --output table for human-readable output; default is JSON.
• For CI/CD, use GPLAY_SERVICE_ACCOUNT environment variable.
• Upload deobfuscation files after each release for crash symbolication.
• Use --dry-run in CI to validate releases before actual deployment.