gpc-release-flow

GPC リリースフロー

使用する場面

次のような作業を行う場合に、このスキルを使用します。

• AAB/APK ファイルを Google Play にアップロードする
• 任意のトラック（内部テスト、アルファ、ベータ、本番）でリリースを作成する
• トラック間でリリースを昇格する
• 段階的な公開を管理する（割合の引き上げ、一時停止、再開、完了）
• リリースノートを設定する
• エンドツーエンドのリリースワークフローに gpc publish を使用する
• gpc validate で送信前の検証を行う
• トラック間のリリース状況を確認する
• 非公開アプリを更新する（v0.9.56 以降で gpc enterprise publish を使って作成）— 初回のカスタムアプリ作成後は、割り当てられた packageName に対して、このスキルの標準コマンドを使用して以降のすべての操作を行います

このスキルの対象外：

• Managed Google Play 用の新しい非公開アプリを作成する場合は、gpc-enterprise（v0.9.56 以降）を使用してください。作成後、バージョンのアップロードとトラック管理については、ここに戻ってください。

必要な入力

• AAB/APK ファイルのパス
• 対象トラック（内部テスト、アルファ、ベータ、本番、またはカスタム）
• 公開割合（段階的な公開の場合）
• リリースノート（コマンド内に直接記述、またはファイルから読み込み）
• --dry-run を指定するかどうか（実行せずにプレビューする場合）

手順

0) 事前検証

アップロード前に、事前コンプライアンススキャナーを実行し、バンドルを検証します。

# Policy compliance scan (offline -- checks manifest, permissions, 64-bit, secrets)
gpc preflight app-release.aab --fail-on error
gpc preflight app-release.apk --fail-on error  # APK: manifest checks run on AABs only

# File format and track validation
gpc validate app-release.aab
gpc validate app-release.aab --track beta  # Validate for specific track

gpc preflight は、AAB/APK が Google Play のポリシー（対象 SDK、権限、ネイティブライブラリなど）に準拠しているかを確認します。gpc validate は、ファイル形式、バージョンコードの競合、トラックとの互換性を確認します。

1) アップロードとリリース

A) クイックリリース（1 つのコマンド）

publish コマンドで、アップロード、トラックの割り当て、リリースノートの設定、コミットまでの一連の処理を実行できます。

gpc publish app-release.aab --track internal
gpc publish app-release.aab --track beta --notes "Bug fixes and improvements"
gpc publish app-release.aab --track production --rollout 10

# Set in-app update priority (0-5) so clients can prompt updates (v0.9.70+)
gpc publish app-release.aab --track production --rollout 10 --in-app-update-priority 5

# Retain older version codes alongside the new upload (v0.9.70+)
gpc publish app-release.aab --track production --retain-version-codes 42,43

# Validate only — run the full pipeline (upload, track assignment, validate) but stop
# before committing. Useful for CI dry-validation against the real API. (v0.9.68+)
gpc publish app-release.aab --track beta --validate-only

ディレクトリから複数言語のリリースノートを設定する場合：

gpc publish app-release.aab --track beta --notes-dir ./release-notes/
# Falls back to default.txt when a locale-specific file is missing (v0.9.70+)

B) 手順ごとのリリース

より細かく制御するには、個別のコマンドを使用します。

# Upload AAB (creates edit, uploads, assigns to track)
gpc releases upload app-release.aab --track internal

# Upload APK (auto-detected, uses correct endpoint)
gpc releases upload app-release.apk --track internal

# Upload with staged rollout
gpc releases upload app-release.aab --track production --rollout 10

# Upload as draft (not visible to users until explicitly released)
gpc releases upload app-release.aab --track production --status draft

# Validate only — upload and validate but do not commit (v0.9.68+)
gpc releases upload app-release.aab --track beta --validate-only

# Set release notes
gpc releases notes set --track beta --lang en-US --notes "Bug fixes"
gpc releases notes set --track beta --file release-notes/  # From directory

v0.9.47 の新機能： APK ファイルは自動検出され、適切な edits.apks.upload エンドポイントからアップロードされます。--status draft を使うと、Play Console で手動確認してから公開する下書きリリースを作成できます。

npm への公開（v0.9.77 以降）： GPC パッケージは、Trusted Publisher（OIDC）と段階的公開を通じて公開されます。CI がパッケージを自動的にステージングし、メンテナーが公開前に 2FA で承認します。長期間有効な NPM_TOKEN は使用しません。CI/CD ワークフローの詳細は gpc-ci-integration を参照してください。

追加のアップロードフラグ（v0.9.51+）

# Upload native debug symbols (ProGuard mapping or native code symbols)
gpc releases upload app.aab --track internal --mapping-type proguard  # default
gpc releases upload app.aab --track internal --mapping-type nativeCode

# Target a specific device tier configuration
gpc releases upload app.aab --track production --device-tier-config 12345
gpc releases upload app.aab --track production --device-tier-config LATEST

# Skip sending changes for review (required for rejected apps)
gpc releases upload app.aab --track production --changes-not-sent-for-review

# Fail safely if there are changes already in review
gpc releases upload app.aab --track production --error-if-in-review

フラグ	値	説明
--mapping-type	proguard（デフォルト）、nativeCode	バンドルとともにアップロードするデバッグシンボルの種類を指定します。ネイティブ（C/C++）ライブラリを配布する場合は、nativeCode を使用します
--device-tier-config	数値 ID または LATEST	デバイス階層のターゲティング設定を適用し、デバイスの種類ごとに異なる APK を配信します。gpc device-tiers create --file tiers.json で設定を作成します。セレクターに、リリースされたばかりのモデルなど、Play がまだカタログに登録していないデバイスを指定する場合は、--allow-unknown-devices（v0.9.96+）を追加してください。追加しない場合、Play は設定を拒否します
--changes-not-sent-for-review	ブール値フラグ	変更を審査に送信せずに編集を確定します。以前の提出が拒否され、まだ再審査の準備ができていない場合に必要です
--error-if-in-review	ブール値フラグ	すでに審査中の変更がある場合、暗黙に上書きするのではなく、コマンドをゼロ以外のコードで終了させます
--validate-only	ブール値フラグ	アップロードと検証の全工程を実行しますが、edits.commit の前に停止します。検証後、編集は削除されます。CI のマージ前チェックに便利です（v0.9.68+）
--in-app-update-priority	0-5	このリリースのアプリ内アップデートの優先度を設定します。0 = デフォルト（緊急性なし）、5 = 最優先。Play Core のアプリ内アップデート API を使用するクライアントは、この値を読み取り、柔軟なアップデートまたは即時アップデートのプロンプトを表示するかどうかを判断できます（v0.9.70+）
--retain-version-codes	カンマ区切り	新しいアップロードとともに保持するバージョンコードをカンマ区切りで指定します。新しいリリースによって古い APK/AAB が無効化されるのを防ぎます（v0.9.70+）

Fastlane 形式の変更履歴のフォールバック（v0.9.70+）

--notes-dir を使用していて、指定したロケールのファイルが存在しない場合、GPC は変更履歴ディレクトリ内の default.txt にフォールバックします。これは Fastlane の規約に合わせたもので、記載のないロケールでリリースノートが空になるのを防ぎます。

拒否されたアプリ

Google Play が提出を拒否すると、アプリは「審査中の変更」状態になります。この状態に対処しない限り、その後のアップロードやプロモーションは失敗します。

1. 新たな審査を開始せずに変更を反映したい場合（例：拒否理由への対応中にメタデータを更新する場合）は、--changes-not-sent-for-review を使用します。編集を確定しますが、審査状態はそのまま維持されます。
2. 審査中の変更を誤って上書きしないようにしたい場合（例：保留中の審査を上書きしてはならない CI パイプラインの場合）は、--error-if-in-review を使用します。変更が審査中の場合、コマンドはコード 4（API エラー）で終了します。
3. 再審査に提出する準備ができている場合は、両方のフラグを省略して通常どおりアップロードします。Google Play は保留中の提出を新しい提出に置き換えます。

これらのフラグは、gpc releases upload、gpc publish、gpc releases promote、gpc releases rollout、gpc listings push/update/delete、gpc listings images upload/delete、gpc testers add/remove/import、gpc tracks create/update、gpc apps update に適用されます。

注（v0.9.52+）： --changes-not-sent-for-review が設定されている場合、GPC はサーバー側の編集検証（edits.validate）をスキップし、edits.commit に直接進みます。Google の検証エンドポイントは changesNotSentForReview パラメーターを受け付けず、アップデートが拒否されたアプリの編集を拒否するため、これは必須です。変更は commit 呼び出し自体によって引き続き検証されます。 参照：

• references/upload-lifecycle.md

2) リリースのステータスを確認する

# Full picture — releases, vitals, and reviews in one command
gpc status

# Releases only, all tracks
gpc releases status

# Specific track detail
gpc releases status --track production

# JSON for scripting
gpc status --output json | jq '.releases[] | select(.track == "production")'

3) トラック間でプロモーションする

# Promote from internal to beta
gpc releases promote --from internal --to beta

# Promote from beta to production with staged rollout
gpc releases promote --from beta --to production --rollout 5

# Copy release notes from another track when promoting
gpc releases promote --from internal --to production --copy-notes-from internal

# Promote as draft (review in Play Console before going live)
gpc releases promote --from internal --to beta --status draft

注： v0.9.39 以降、gpc releases promote は 409 EDIT_CONFLICT（別の編集が開いている場合）に対して自動で 1 回再試行します。

プロモーションでも審査制御フラグをサポートしています（v0.9.51+）：

# Promote without sending for review (rejected app workflow)
gpc releases promote --from internal --to beta --changes-not-sent-for-review

# Fail if changes are already in review
gpc releases promote --from beta --to production --rollout 5 --error-if-in-review

3b) 公開前にプレビューする

# Read-only preview of release state across all tracks
gpc diff

# Compare two specific tracks
gpc diff --from internal --to production

# Compare local metadata vs remote
gpc diff --metadata fastlane/metadata

3c) リリースライフサイクルの可視化

# List releases on a track with lifecycle states (DRAFT, IN_REVIEW, PUBLISHED, etc.)
gpc releases list --track production
gpc releases list --track beta --json

v0.9.46 の新機能： releases.list エンドポイントを使うと、編集セッションを開始せずにリリースのライフサイクル状態を確認できます。リリースがまだ審査中か、公開済みか、下書きかを確認する際に使用してください。審査の完了を条件とする必要がある CI パイプラインに便利です。

3d) リリースの統計情報と履歴

# Release count per track with status breakdown
gpc releases count

# Show release history from GitHub
gpc changelog
gpc changelog --tag v0.9.47

# Generate GitHub Release notes from local commits (v0.9.61+)
gpc changelog generate                              # markdown for the next release
gpc changelog generate --format prompt | pbcopy     # paste into Claude/ChatGPT
gpc changelog generate | gh release create vX -F -  # one-command release
gpc changelog generate --strict                     # fail CI on linter warnings (jargon, scope leaks)

::: tip 2 種類のリリースノートのフロー

• Play Store の recentChanges[]（ロケールごと、500 文字）：gpc changelog generate --target play-store --locales auto --ai --apply（v0.9.64 以降、エンドツーエンド）または gpc publish --notes-from-git --since vX
• GitHub Release のノート（標準の Markdown テンプレート、スマートなクラスタリング、LLM プロンプトモード）：gpc changelog generate（v0.9.61 以降） :::

Play Store リリースノートの多言語対応（v0.9.62 以降）

ロケールごとの Play Store「新機能」テキストを指定するには、--target play-store と --locales を渡します。

# Translate via your own LLM key (BYO, v0.9.63+)
gpc changelog generate --target play-store --locales auto --ai

# Explicit locales, no AI — placeholder text for non-source locales
gpc changelog generate --target play-store --locales en-US,fr-FR,de-DE

# Auto-detect from your live Play listing (one API round-trip)
gpc changelog generate --target play-store --locales auto --app com.example.app

# Preview the prompt without spending tokens
gpc --dry-run changelog generate --target play-store --locales auto --ai

主な動作：

• en-US のソースは github ターゲットと同じ箇条書きで、500 Unicode コードポイントを超える場合は切り詰められます。
• --ai を指定した場合（v0.9.63 以降）：ソース以外のロケールは、ユーザー自身の LLM キーを使って翻訳されます。環境変数を優先順位順に自動検出します：AI_GATEWAY_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY → GOOGLE_GENERATIVE_AI_API_KEY。デフォルトは推論を行わないモデルです（claude-sonnet-4-6、gpt-4o-mini、gemini-2.5-flash）。--provider／--model で上書きできます。
• --ai を指定しない場合：ソース以外のロケールには [needs translation] プレースホルダーが設定されます。オフラインまたはキーを使わないワークフロー向けに、翻訳用の LLM プロンプトを出力するには --format prompt を使用します。
• --strict は、いずれかのロケールが 500 文字を超えた場合、または（--ai を指定した場合）いずれかのロケールの翻訳に失敗した場合に、終了コード 1 で終了します。
• 遅延読み込み：--ai を指定せずに実行すると、AI SDK の依存関係は一切インポートされません。コールドスタートの予算を維持します。
• AI SDK v6（v0.9.82 以降）：基盤となる @ai-sdk/* パッケージが 5.x から 6.0 にアップグレードされました。公開されている --ai インターフェースとすべてのモデルプロバイダーオプションに変更はありません。ユーザー側で移行作業を行う必要はありません。

翻訳済みノートを下書きリリースに書き込む（v0.9.64 以降）

リリースノートを生成したら（--ai の有無を問わず）、Play Store トラック上の最新の下書きに直接書き込みます。

# Full pipeline: generate + translate + apply
gpc changelog generate --target play-store --locales auto --ai --apply

# Apply to a specific track (default: production)
gpc changelog generate --target play-store --locales auto --ai --apply --track beta

# Preview what would be written (no API call)
gpc changelog generate --target play-store --locales auto --ai --apply --dry-run

主な動作：

• --apply には --target play-store が必要です（--format prompt とは併用できません）。
• トラック上の最新の下書きに書き込みます。下書きがない場合は RELEASE_NO_DRAFT（終了コード 1）で終了し、先に下書きを作成するよう促します。
• 409 編集競合には withRetryOnConflict を使用します。
• --dry-run は API に変更を加えず、書き込まれるノートを表示します。

バンドルアップロードの競合を修正（v0.9.64 以降、v0.9.77 で拡張）： 大容量の AAB（65MB 以上）をアップロードした後、GPC は edits.validate を呼び出す前に、フィボナッチバックオフ（2s、3s、5s、8s、13s、21s、34s――合計約 86s）を使って bundles.list をポーリングします。これにより、すべての AAB アップロード経路で発生していた、一時的な INVALID_ARGUMENT: Some of the Android App Bundle uploads are not completed yet エラーが修正されます。サーバー側のこの処理待ちに対応していることが知られている CLI は GPC のみです。Google の API ドキュメントには、この非同期動作について記載がありません。

validate／commit の複数回再試行ガード（v0.9.77）： バンドルの処理完了後、edits.validate と edits.commit はそれぞれ、タイムアウトを段階的に延長しながら（15s、30s、45s）最大 3 回再試行します。バンドルの処理は完了しているものの、編集内容をまだコミットできない一時的なサーバー側の遅延に対応します。

Vercel AI Gateway の経路（実行ごとのコストを USD で報告）を含む詳しい手順については、apps/docs/guide/multilingual-release-notes.md を参照してください。

4) 段階的な公開を管理する

# Increase rollout percentage
gpc releases rollout increase --track production --to 50

# Halt rollout (stops further distribution)
gpc releases rollout halt --track production

# Resume halted rollout
gpc releases rollout resume --track production

# Complete rollout (100%)
gpc releases rollout complete --track production

ロールアウトコマンドでは、審査制御フラグもサポートされています（v0.9.51 以降）。

# Increase rollout without triggering review (rejected app workflow)
gpc releases rollout increase --track production --to 50 --changes-not-sent-for-review

# Complete rollout, but fail if there are changes in review
gpc releases rollout complete --track production --error-if-in-review

参照：

• references/rollout-strategies.md

5) トラック管理

gpc tracks list                    # List all tracks
gpc tracks get production          # Show track details + current releases

v0.9.87 の新機能： tracks list --json が、他の list コマンドと同じ統一エンベロープ { tracks, nextPageToken, meta.count } を返すようになりました。テーブル出力に変更はありません。変更されたのは --json の形式のみです。

既存のバージョンコードを別のトラックに割り当てる（v0.9.78+）

AAB がすでにアップロードされている場合、再アップロードせずにそのバージョンコードを別のトラックに割り当てられます。

gpc releases assign 42 --track beta
gpc releases assign 42 --track production --rollout 10

これは、バージョンコードをあるテストトラックから別のトラックに移したい場合や、CI ビルドで内部テストにアップロードしたものを、より多くのユーザーに公開するためにアルファ版に割り当てたい場合に便利です。

カスタムのクローズドテストトラックを作成する（v0.9.79+）

Google Play では、組み込みの internal、alpha、beta、production トラックに加えて、カスタムのクローズドテストトラックを利用できます。

gpc tracks create --track-id my-custom-track --name "Partner Testing"

内部では edits.tracks.create を使用します。作成後は、任意の --track フラグでカスタムトラック ID を使用してください。

6）ドライランでプレビューする

すべての書き込み操作で --dry-run を使用できます。

gpc releases upload app.aab --track beta --dry-run
gpc releases promote --from beta --to production --rollout 10 --dry-run
gpc releases rollout increase --track production --to 50 --dry-run

--json と --dry-run を併用すると、出力に executed[] と skipped[] の配列が含まれ、CI パイプラインで実行されるはずだった手順を確認できます（v0.9.79+）。

{
  "dryRun": true,
  "executed": [],
  "skipped": ["upload", "validate", "commit"]
}

7）対話モード

フラグを省略すると、TTY が検出された場合に GPC が対話形式でプロンプトを表示します。

gpc releases upload app.aab
# Prompts for: track, rollout percentage, release notes

--no-interactive または GPC_NO_INTERACTIVE=1 で無効にできます。

検証

• gpc status で、リリースが想定どおりのトラックにあり、ステータスと段階的公開が正しいことを確認します
• gpc releases status で、バージョンコードがアップロード済みの AAB と一致することを確認します
• 段階的公開の割合が正しいことを確認します
• 想定する言語のリリースノートが設定されていることを確認します
• リリース後に gpc vitals crashes --dim versionCode で急増がないことを確認します（または gpc status で全指標のバイタルを確認します）

失敗の原因とデバッグ

症状	考えられる原因	解決方法
Version code already used	このトラックに同じバージョンコードが存在します	ビルドの versionCode を増やします
APK_NOT_SIGNED	署名がないか、無効です	Play App Signing を使用するか、キーストアを確認します
EDIT_CONFLICT	別の編集処理が進行中です	待ってから再試行するか、Console UI で保留中の編集を破棄します
段階的公開が停止したまま	段階的公開が中断されています	gpc releases rollout resume --track <track>
トラックが違う	間違ったトラックに昇格しました	正しいトラックで新しいリリースを作成します
API_DECLARATION_REQUIRED	Play Console のアプリのコンテンツに関する申告が未完了です（v0.9.94+）	Policy > App content で完了させます。メッセージを確認してください。GPC は Google のメッセージを引用し、該当する申告を具体的に示します。権限の問題ではありません
正しいと思われるサービスアカウントで API_INSUFFICIENT_PERMISSIONS が発生する	v0.9.94 より前の GPC では、アプリのコンテンツに関する申告が原因であることが多く、誤って報告されていました	アップグレードするか、ロールを変更する前に Policy > App content を確認します

コミットが拒否される場合：reviewPending と nextStep（v0.9.79+）

変更を審査に通す必要があるため Google Play が edits.commit 呼び出しを拒否すると、GPC は通常のエラーではなく、構造化された結果を返します。

{
  "reviewPending": true,
  "nextStep": "Your changes are under Google review. Check Play Console for status or use --changes-not-sent-for-review to bypass review for non-reviewed tracks."
}

reviewPending フィールドは常にブール値です。nextStep 文字列には、人が読めるガイダンスが含まれます。CI パイプラインでは reviewPending === true を条件に、ポーリング、通知、または終了を判断できます。

内部テストトラックでは審査をスキップ（v0.9.79+）

内部テストトラックでは Google の審査は不要です。internal トラックへのコミット時、GPC は構造化された出力に reviewSkipped: true を設定し、審査キューに入らず、コミットが即座に完了したことを示します。

参照：

• references/troubleshooting.md
• references/pre-release-pipeline.md — 検証からアップロード、バイタルのゲート判定、昇格、段階的公開までのエンドツーエンドの手順

8）リアルタイム デベロッパー通知（RTDN）

サブスクリプションと購入イベントをリアルタイムで監視します。

gpc rtdn status              # Check Pub/Sub topic configuration
gpc rtdn decode <payload>    # Decode base64 notification payload
gpc rtdn test                # Guidance for testing RTDN setup

以前から確認されていたバグ（v0.9.78 で修正済み）

以下の項目はすべて v0.9.78 で解決済みです。過去の情報としてのみ記載しています。

バグ	ステータス
tracks update を実行すると、トラックが通知なく消去される	修正済み：versionCode の型変換とネストされた JSON のサポート
--changes-not-sent-for-review フラグが API に渡されない	修正済み：検証時に validateAndCommit が自動的に復旧（15 個以上のコマンド）
すでにアップロード済みの versionCode を再アップロードせずに新しいトラックに割り当てられない	修正済み：gpc releases assign <versionCode> --track <track>

関連スキル

• gpc-setup：認証と設定
• gpc-metadata-sync：ストアの掲載情報とスクリーンショット
• gpc-vitals-monitoring：リリース後のクラッシュ監視
• gpc-ci-integration：CI/CD での自動リリース
• gpc-monetization：サブスクリプション、IAP、RTDN 通知
• gpc-enterprise：Play Custom App Publishing API による Managed Google Play への非公開アプリの公開（v0.9.56+）