gpc-metadata-sync

GPC メタデータの同期

使用する場面

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

• ストア掲載情報（タイトル、説明、短い説明文）の表示や更新
• ローカルファイルと Google Play Console 間でメタデータを同期する
• スクリーンショットや画像の管理（アップロード、削除、一覧表示）
• Fastlane 互換のメタデータディレクトリ構造を扱う
• 多言語の掲載情報を管理する
• バージョン管理のために掲載情報をローカルに取得する
• ローカルの掲載情報を Play Console に送信する

必要な入力

• パッケージ名（または GPC_APP で設定されたデフォルト値）
• 言語コード（例：en-US、ja-JP）
• プッシュ／プルの場合：メタデータファイル用のローカルディレクトリパス
• 画像の場合：画像タイプとファイルパス

手順

0) 現在の掲載情報を表示する

# Default language listing
gpc listings get

# Specific language
gpc listings get --lang ja-JP

# All languages at once (omit --lang)
gpc listings get

# JSON output for scripting
gpc listings get --output json

1) 掲載情報をインラインで更新する

gpc listings update --lang en-US \
  --title "My App" \
  --short "A great app for great things" \
  --full "Full description here..."

または、説明文全体をファイルから読み込みます。

gpc listings update --lang en-US --full-file metadata/en-US/full_description.txt

Fastlane 形式のディレクトリからすべてのロケールを一度に更新するには、gpc listings push --dir metadata/ を使用します（セクション 2）。

1a) 掲載情報をローカルで検証する（lint）

API 呼び出しを行わずにローカルで検証し、プッシュ前に文字数制限を確認します。

gpc listings lint

# Point at a specific metadata directory
gpc listings lint --dir metadata/
gpc listings lint --dir fastlane/metadata/android/

出力テーブル：

Field             Chars  Limit   %    Status
────────────────────────────────────────────
title              28     30    93%    ✓
shortDescription   76     80    95%    ✓
fullDescription   3820   4000   96%    ✓
video URL          0      256    0%    ✓

適用される文字数制限：title = 30、shortDescription = 80、fullDescription = 4000、動画 URL = 256。

いずれかのフィールドが制限を超えると、終了コード 1 を返します。コミット前またはプッシュ前のチェックとして使用します。

1b) ライブ掲載情報を検証する（analyze）

Play ストアからライブ掲載情報を取得し、同じ文字数制限チェックを実行します。

gpc listings analyze

# Compare against an expected set of locales
gpc listings analyze --expected en-US,ja-JP,de-DE

# JSON output
gpc listings analyze --json

lint と同じ出力テーブルですが、現在 Play ストアで公開されている内容が反映されます。--expected フラグを指定すると、掲載情報のリストに含まれているのに Play Console にないロケール（またはその逆）を検出します。

2) プル／プッシュのワークフロー（双方向同期）

掲載情報をバージョン管理する場合に推奨されるワークフローです。

プル（Play Console からローカルにダウンロード）：

gpc listings pull --dir metadata/

次のディレクトリ構造が作成されます。

metadata/
├── en-US/
│   ├── title.txt
│   ├── short_description.txt
│   ├── full_description.txt
│   └── changelogs/
│       └── 142.txt
├── ja-JP/
│   ├── title.txt
│   ├── short_description.txt
│   └── full_description.txt
└── ...

プッシュ（ローカルファイルを Play Console にアップロード）：

gpc listings push --dir metadata/

# Prevent changes from being auto-submitted for review
gpc listings push --dir metadata/ --changes-not-sent-for-review

# Fail if the app is currently in review or rejected
gpc listings push --dir metadata/ --error-if-in-review

# Preview changes without applying
gpc listings push --dir metadata/ --dry-run

# Bypass the preflight lint gate (not recommended)
gpc listings push --dir metadata/ --force

事前チェックの lint ゲート： gpc listings push はアップロード前に gpc listings lint を自動実行します。いずれかのフィールドが文字数制限を超えていると、終了コード 1 でプッシュが中止されます。ゲートをスキップしてプッシュを続行するには、--force を指定します。

参照：

• references/directory-structure.md

3) Fastlane との互換性

GPC は Fastlane のメタデータディレクトリ形式の読み込みと書き込みに対応しています。Fastlane から移行する場合：

# Your existing Fastlane metadata/ directory works as-is
gpc listings push --dir fastlane/metadata/android/

# Pull into Fastlane-compatible structure
gpc listings pull --dir fastlane/metadata/android/

参照：

• references/fastlane-migration.md

4) 画像の管理

既存の画像を一覧表示する：

gpc listings images list --lang en-US --type phoneScreenshots

画像タイプ：phoneScreenshots、sevenInchScreenshots、tenInchScreenshots、tvScreenshots、wearScreenshots、icon、featureGraphic、tvBanner、promoGraphic。

画像をアップロードする：

# Single image
gpc listings images upload --lang en-US --type phoneScreenshots screenshot.png

# Multiple images (glob)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png

# Preview what would be uploaded without making API calls (v0.9.74+)
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run

画像を削除する：

gpc listings images delete --lang en-US --type phoneScreenshots --id <image-id>

# Preview what would be deleted without making API calls (v0.9.74+)
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run

v0.9.74 の新機能： gpc listings images upload と gpc listings images delete のどちらも --dry-run に対応しました。ドライランモードでは、Play API を呼び出さずに、実行される内容（アップロード対象のファイル、削除対象の画像 ID）をコマンドに表示します。

AI 生成画像の申告（v0.9.96 以降）

Google Play では、AI が生成したストア画像を開発者が申告する必要があります。アップロード時にこの申告を記録するには --ai-generated を指定します。指定しない場合、申告なしで画像がアップロードされます。このフラグは images upload と images sync の両方で使用できます。sync では、実行時にアップロードされるすべての画像に適用されるため、AI 生成画像のセットは、異なる画像が混在するディレクトリとは分けて実行してください。

gpc listings images upload ./screenshots/hero.png \
  --app com.example.app --lang en-US --type phoneScreenshots --ai-generated

gpc listings images sync --dir ./ai-screens --lang en-US --type phoneScreenshots --ai-generated

ローカルディレクトリから画像を同期する（v0.9.69+）— 画像ごとのアップロード／削除よりこちらを優先してください

gpc listings images sync は SHA-256 のコンテンツハッシュを使って画像を重複排除します。Play Store にまだないファイルだけをアップロードし、必要に応じてローカルに対応するファイルがないリモート画像を削除します。すべての処理を1回の Play 編集と1回のコミットで実行します。

保存枠のルール（重要 — まずは必ず sync を使ってください）。 Google がアプリごとに設けている公開（保存）上限は、一般的な API リクエストのクォータを大幅に下回っており、コミットした編集はそれぞれ1回の保存としてカウントされます。画像ごとの gpc listings images upload コマンドと gpc listings images delete コマンドはそれぞれ独自に編集を開始してコミットするため、多数のロケールに対して繰り返すと、呼び出しごとに1回の保存枠を消費します。たとえば、削除してからアップロードする方法で、5枚の画像 × 27ロケール × 2フォームファクターを処理すると、1回の実行で約540回の保存となり、数回の実行で1日の上限に達します。sync --dir（必要に応じて --delete）を使えば、実行全体を1回の保存にまとめられます。また、変更のない再実行はコミットせず破棄されるため、保存枠を消費しません。単独の upload／delete コマンドを使うのは、1枚の画像だけを本当に個別に修正する場合に限ってください。

# Sync EVERY locale and image type under a tree, mirror deletions — one save for the whole run
gpc listings images sync --dir ./images --delete

# Sync all phone screenshots for en-US from a local directory
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/

# Sync all image types for a language
gpc listings images sync --lang en-US --dir ./screenshots/en-US/

# Preview what would change without touching the API (spends no save)
gpc listings images sync --dir ./images --delete --dry-run

主な動作：

• ローカルの各ファイルの SHA-256 ハッシュをリモート画像のハッシュと比較します。一致する画像はスキップされ、再アップロードされません。
• 実行全体を1回の編集と1回のコミットで処理するため、保存枠の消費は1回です（変更がなければ0回）。これはクォータに安全な方法です。上記の保存枠のルールを参照してください。
• --delete を指定すると、一致するローカルファイルがないリモート画像を削除します。このフラグを指定しない場合、余分なリモート画像はそのまま残ります。
• --delete を指定すると表示順を保証（v0.9.92+）： Play API には並べ替え用のエンドポイントがなく、アップロード順が維持されます。そのため、ハッシュのみを使った部分更新では、変更されていない画像の位置はそのまま、変更された画像は末尾に追加され、スクリーンショットの順序が崩れます。ロケール／種類の組み合わせで、内容または順序がローカルと異なる場合、--delete はその組み合わせの画像を1回の呼び出しで消去し、ローカルファイルをファイル名の昇順（1.png、2.png、...）で再アップロードします。すでに順序が一致している組み合わせはスキップされます。表示順に並ぶようにファイル名を付けてください。種類ごとの上限に近い場合はゼロ埋め（01.png）を使ってください。
• ディレクトリ不在時の安全性（v0.9.92+）： ローカルに存在しない種類のディレクトリは変更されないため、スクリーンショットだけを同期しても、リモートのアイコンやフィーチャーグラフィックが消去されることはありません。存在するものの空のディレクトリは、その種類を明示的に「消去」する指定です。
• ディレクトリ読み取り不可時の安全性（v1.0.0-rc.1+）： ローカルの画像ディレクトリが存在するものの、読み取りできない場合（権限の問題、または CI コンテナ内のボリューム所有権の問題）、同期は IMAGE_SYNC_DIR_UNREADABLE（終了コード 1）で停止し、Google Play 上の内容は変更されません。以前のバージョンでは空のディレクトリとして読み取られていたため、--delete によって対応するリモート画像が消去される可能性がありました。このエラーが発生するのは実際に読み取りに失敗した場合のみです。ディレクトリが単に存在しない場合は引き続きスキップされます。
• --dry-run は API を呼び出さずに、差分テーブル（add / skip / delete）を表示します。
• gpc listings images upload と同じ画像の種類に対応しています：phoneScreenshots、sevenInchScreenshots、tenInchScreenshots、tvScreenshots、wearScreenshots、icon、featureGraphic、tvBanner、promoGraphic。

フラグ	説明
--dir	同期する画像ファイルを含むローカルディレクトリ
--lang	言語コード（例：en-US、ja-JP）
--type	画像の種類のフィルター（ディレクトリ内のすべての種類を同期する場合は省略）
--delete	ローカルに対応するファイルがないリモート画像を削除
--ai-generated	この実行でアップロードするすべての画像が AI によって生成されたことを証明（v0.9.96+）
--dry-run	アップロードや削除を行わずに変更内容をプレビュー

5) 多言語ワークフロー

多言語対応アプリの場合：

# Pull all languages
gpc listings pull --dir metadata/

# Edit locally (use your preferred text editor or translation tools)

# Push all languages back
gpc listings push --dir metadata/ --dry-run  # Preview first
gpc listings push --dir metadata/ --changes-not-sent-for-review  # Apply without auto-submitting for review

ヒント：（すべてのリスティング項目ではなく）ロケールごとの「新機能」リリースノートのテキストを生成するには、gpc changelog generate --target play-store（v0.9.62+）を参照してください。Git ログを読み込み、Play ストアの500文字制限を適用したロケールごとの出力を生成します。--ai（v0.9.63+）を追加すると、独自の LLM キーを使用してソース言語以外のロケールを翻訳できます（AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY を自動検出します）。

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

すべての書き込み操作は --dry-run に対応しています。

gpc listings update --lang en-US --title "New Title" --dry-run
gpc listings push --dir metadata/ --dry-run
gpc listings images upload --lang en-US --type phoneScreenshots ./screens/*.png --dry-run
gpc listings images delete --lang en-US --type phoneScreenshots --dry-run
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screens/ --dry-run

ドライランモードでは API 呼び出しは行われません。出力には、変更される内容（アップロードされるファイル、削除される画像 ID、更新される項目）が記載されます。

検証

• gpc listings get --lang <lang> で更新された内容を確認できます
• gpc listings get（--lang なし）で、すべての言語が正しいことを確認できます
• gpc listings images list --lang <lang> --type <type> でアップロード済みの画像を確認できます
• Play Console の UI に変更が反映されます（数分かかる場合があります）

セキュリティに関する注意事項（v0.9.74+）

--notes-dir でのシンボリックリンク走査保護

--notes-dir を使用してリリースノートを読み込む場合（例：gpc releases upload --notes-dir changelogs/）、GPC はすべてのエントリに対して lstat() を呼び出し、ファイルの内容を読み取る前にシンボリックリンクを拒否するようになりました。これにより、ノートディレクトリ内の細工されたシンボリックリンクがディレクトリツリー外の機密ファイル（例：/etc/passwd、SSH キー）を指す、ディレクトリトラバーサル攻撃を防ぎます。

シンボリックリンクが見つかると、問題のパスを示すわかりやすいエラーを表示してコマンドは終了します。ノートディレクトリには実ファイルを使用してください。

レビューのエクスポートにおける CSV 数式インジェクションの防止

gpc reviews export および CSV 出力を生成するその他のコマンドでは、=、+、-、@、タブ（\t）、またはキャリッジリターン（\r）で始まるセルの先頭にシングルクォート（'）を付けるようになりました。これにより、CSV を開いたときに、スプレッドシートアプリケーション（Excel、Google Sheets）がユーザー入力の内容（レビューのテキスト、アプリのタイトル）を数式として解釈するのを防ぎます。

CSV をプログラムで処理する場合は、必要に応じて文字列値の先頭にある ' を取り除いてください。

失敗時の症状／デバッグ

症状	考えられる原因	対処法
LISTING_NOT_FOUND	Play Console で言語が設定されていない	先に Console で言語を追加してから、プッシュします
数回実行した後に、1日の保存／公開クォータを超過する	画像ごとに upload／delete をループしている（確定した編集1回につき保存が1回必要）	gpc listings images sync --dir ... --delete（実行全体で保存1回）に切り替え、テキストには gpc listings push --dir を使用します。セクション4の保存クォータのルールを参照してください。
一部更新後にスクリーンショットの表示順が乱れる	古い GPC を使用している、または画像ごとのアップロードで変更画像が最後に追加される	v0.9.92+ にアップグレードして sync --delete を使用します（順序が保証されます）。ファイル名は 1.png、2.png、... のようにします
IMAGE_SYNC_DIR_UNREADABLE（終了コード1）	ローカルの画像ディレクトリは存在するが、読み取れない（権限、CI ボリュームの所有権）	ディレクトリの権限を修正して再実行します。Google Play 上の内容は変更されていません（v1.0.0-rc.1+）
画像のアップロードに失敗する	形式またはサイズが正しくない	Google の画像要件（PNG/JPEG、種類ごとのサイズ制限）を確認します
説明文が途中で切れる	文字数制限を超えている	タイトル：30文字、短い説明：80文字、全説明：4000文字
プッシュしても変更が表示されない	ローカルファイルがリモートと一致している	編集内容が正しいファイルパスに保存されていることを確認します
エンコーディングの問題	ファイルのエンコーディングが UTF-8 ではない	すべてのテキストファイルが UTF-8 でエンコードされていることを確認します

関連スキル

• gpc-setup：認証と設定
• gpc-release-flow：アップロードとリリース管理
• gpc-ci-integration：CI/CD でのメタデータ同期の自動化