Back to Details

gplay-release-flow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Release flow (Internal, Beta, Production)

发布流程（内部测试、Beta测试、正式发布）

Use this skill when you need to get a new build onto Google Play Store.
当你需要将新构建包上传至Google Play商店时，可以使用本技能。

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.
  • 确保已配置凭证（执行
    gplay auth login
    或设置
    GPLAY_SERVICE_ACCOUNT
    环境变量）。
  • 构建包必须为AAB（App Bundle）或APK格式。
  • 版本号必须高于之前的发布版本。
  • 服务账号需在Play Console中拥有「发布管理员」权限。

Android Release

Android应用发布

Preferred end-to-end commands

推荐的端到端命令

Internal track (for internal testing):
bash
gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab
Beta track (for beta testers):
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --release-notes @release-notes.json
Production with staged rollout (gradual release):
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --rollout 10
Dry run (preview the release without executing):
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --dry-run
内部测试渠道（用于内部测试）：
bash
gplay release \
  --package com.example.app \
  --track internal \
  --bundle app-release.aab
Beta测试渠道（用于Beta测试人员）：
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app-release.aab \
  --release-notes @release-notes.json
分阶段正式发布（逐步推广）：
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --rollout 10
模拟发布（预览发布流程但不实际执行）：
bash
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:
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata
Skip metadata or screenshots:
bash
undefined
从目录同步商店列表：
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --listings-dir ./metadata \
  --screenshots-dir ./metadata
跳过元数据或截图上传：
bash
undefined

Upload bundle only, skip metadata sync

仅上传构建包，跳过元数据同步

gplay release
--package com.example.app
--track production
--bundle app-release.aab
--skip-metadata
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**:
```bash
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
gplay release
--package com.example.app
--track production
--bundle app-release.aab
--listings-dir ./metadata
--skip-screenshots

**分开指定列表和截图目录**：
```bash
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:
    bash
    EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
  2. Upload bundle:
    bash
    gplay bundles upload \
  --package com.example.app \
  --edit $EDIT_ID \
  --file app-release.aab
  3. Update track:
    bash
    gplay tracks update \
  --package com.example.app \
  --edit $EDIT_ID \
  --track production \
  --json @track-config.json
  4. Validate edit:
    bash
    gplay edits validate --package com.example.app --edit $EDIT_ID
  5. Commit edit (publishes changes):
    bash
    gplay edits commit --package com.example.app --edit $EDIT_ID
  1. 创建编辑会话：
    bash
    EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
  2. 上传构建包：
    bash
    gplay bundles upload \
  --package com.example.app \
  --edit $EDIT_ID \
  --file app-release.aab
  3. 更新发布渠道：
    bash
    gplay tracks update \
  --package com.example.app \
  --edit $EDIT_ID \
  --track production \
  --json @track-config.json
  4. 验证编辑内容：
    bash
    gplay edits validate --package com.example.app --edit $EDIT_ID
  5. 提交编辑（发布变更）：
    bash
    gplay edits commit --package com.example.app --edit $EDIT_ID

Track Promotion

渠道版本推广

Promote a release from one track to another:
bash
undefined
将版本从一个渠道推广到另一个渠道：
bash
undefined

Promote from internal to beta

从内部测试渠道推广到Beta测试渠道

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

Promote from beta to production with 25% rollout

从Beta测试渠道推广到正式渠道，分25%逐步发布

gplay promote
--package com.example.app
--from beta
--to production
--rollout 25
undefined
gplay promote
--package com.example.app
--from beta
--to production
--rollout 25
undefined

Staged Rollout Management

分阶段发布管理

Start with 10% rollout:
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --rollout 10
Increase to 50%:
bash
gplay rollout update \
  --package com.example.app \
  --track production \
  --rollout 50
Halt rollout (pause distribution):
bash
gplay rollout halt --package com.example.app --track production
Resume rollout:
bash
gplay rollout resume --package com.example.app --track production
Complete rollout (release to 100%):
bash
gplay rollout complete --package com.example.app --track production
初始10%比例发布：
bash
gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --rollout 10
提升至50%比例：
bash
gplay rollout update \
  --package com.example.app \
  --track production \
  --rollout 50
暂停发布：
bash
gplay rollout halt --package com.example.app --track production
恢复发布：
bash
gplay rollout resume --package com.example.app --track production
完成全量发布（推广至100%用户）：
bash
gplay rollout complete --package com.example.app --track production

Release Notes Format

发布说明格式

JSON format (multi-locale)

JSON格式（多语言）

release-notes.json
:
json
{
  "en-US": "Bug fixes and performance improvements",
  "es-ES": "Correcciones de errores y mejoras de rendimiento",
  "fr-FR": "Corrections de bugs et améliorations des performances"
}
release-notes.json
：
json
{
  "en-US": "Bug fixes and performance improvements",
  "es-ES": "Correcciones de errores y mejoras de rendimiento",
  "fr-FR": "Corrections de bugs et améliorations des performances"
}

Plain text format (single locale)

纯文本格式（单语言）

You can also provide release notes as plain text for a single locale:
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes "Bug fixes and performance improvements" \
  --release-notes-locale en-US
Or from a text file:
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes @release-notes.txt \
  --release-notes-locale en-US
你也可以为单一语言提供纯文本格式的发布说明：
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes "Bug fixes and performance improvements" \
  --release-notes-locale en-US
或从文本文件读取：
bash
gplay release \
  --package com.example.app \
  --track beta \
  --bundle app.aab \
  --release-notes @release-notes.txt \
  --release-notes-locale en-US

Release Flags Reference

发布参数参考

FlagDescription
--package
App package name (required)
--track
Target track (required)
--bundle
Path to AAB file (required)
--release-notes
Release notes (JSON file with 
@
, plain text, or text file with 
@
)
--release-notes-locale
Locale for plain text release notes (e.g., 
en-US
)
--rollout
Rollout percentage (1-100)
--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
)
参数说明
--package
应用包名（必填）
--track
目标发布渠道（必填）
--bundle
AAB文件路径（必填）
--release-notes
发布说明（带
@
的JSON文件、纯文本或带
@
的文本文件）
--release-notes-locale
纯文本发布说明的语言区域（例如
en-US
）
--rollout
发布比例（1-100）
--listings-dir
包含待同步商店列表的目录
--screenshots-dir
包含待上传截图的目录
--skip-metadata
发布时跳过元数据/商店列表同步
--skip-screenshots
发布时跳过截图上传
--dry-run
预览发布流程但不实际执行
--output
输出格式（
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
发布前请确认：
  • 版本号已递增
  • AAB/APK已使用正确密钥库签名
  • 已上传ProGuard/R8映射文件（用于崩溃报告）
  • 已为所有语言区域编写发布说明
  • 已在内部/Beta渠道完成测试
  • 服务账号拥有正确权限
  • 模拟发布通过：
    gplay release ... --dry-run

Common Release Strategies

常见发布策略

Strategy 1: Internal -> Beta -> Production
bash
undefined
策略1：内部测试 → Beta测试 → 正式发布
bash
undefined

Week 1: Internal

第1周：内部测试

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

Week 2: Beta (after testing)

第2周：Beta测试（测试完成后）

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

Week 3: Production with staged rollout

第3周：分阶段正式发布

gplay promote --package com.example.app --from beta --to production --rollout 10 gplay rollout update --package com.example.app --track production --rollout 50 # Day 2 gplay rollout complete --package com.example.app --track production # Day 7

**Strategy 2: Direct to Production with Staged Rollout**
```bash
gplay promote --package com.example.app --from beta --to production --rollout 10 gplay rollout update --package com.example.app --track production --rollout 50 # 第2天 gplay rollout complete --package com.example.app --track production # 第7天

**策略2：直接分阶段正式发布**
```bash

Day 1: 10%

第1天：10%比例

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

Day 2: 25%

第2天：25%比例

gplay rollout update --package com.example.app --track production --rollout 25
gplay rollout update --package com.example.app --track production --rollout 25

Day 3: 50%

第3天：50%比例

gplay rollout update --package com.example.app --track production --rollout 50
gplay rollout update --package com.example.app --track production --rollout 50

Day 7: 100%

第7天：全量发布

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

**Strategy 3: Full release with metadata and dry-run verification**
```bash
gplay rollout complete --package com.example.app --track production

**策略3：带元数据的完整发布+模拟验证**
```bash

1. Dry run to verify everything

1. 模拟发布以验证所有内容

gplay release
--package com.example.app
--track production
--bundle app.aab
--listings-dir ./metadata
--screenshots-dir ./metadata
--release-notes @release-notes.json
--rollout 10
--dry-run
gplay release
--package com.example.app
--track production
--bundle app.aab
--listings-dir ./metadata
--screenshots-dir ./metadata
--release-notes @release-notes.json
--rollout 10
--dry-run

2. Execute the release

2. 执行正式发布

gplay release
--package com.example.app
--track production
--bundle app.aab
--listings-dir ./metadata
--screenshots-dir ./metadata
--release-notes @release-notes.json
--rollout 10
undefined
gplay release
--package com.example.app
--track production
--bundle app.aab
--listings-dir ./metadata
--screenshots-dir ./metadata
--release-notes @release-notes.json
--rollout 10
undefined

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.
  • 始终使用
    --help
    查看具体命令的参数说明。
  • 使用
    --output table
    获取易读的人类友好型输出；默认输出格式为JSON。
  • 在CI/CD流程中，使用
    GPLAY_SERVICE_ACCOUNT
    环境变量配置凭证。
  • 每次发布后上传反混淆文件，用于崩溃符号解析。
  • 在CI流程中使用
    --dry-run
    验证发布内容后再执行实际部署。