capgo-release-management

Capgo リリース管理

CLI から Capgo OTA バンドルを配信、昇格、ロールバック、クリーンアップします。

以下の情報は @capgo/cli 8.77（2026 年 10 月）を基に確認済みです。すべてのコマンドで -a, --apikey を使用できます。Capacitor プロジェクト内では appId を省略できます。

使用するタイミング

次の場合に使用します。

• ユーザーがバンドルをアップロード、一覧表示、削除、またはクリーンアップする場合、あるいはチャネルがどのバージョンを配信しているかを尋ねる場合。
• ユーザーがチャネルを作成または設定する場合、ステージングを本番環境に昇格する場合、段階的ロールアウトを開始、一時停止、またはロールバックする場合、あるいは問題のあるリリースをロールバックする場合。
• 変更が OTA セーフかどうかを尋ねる場合（bundle compatibility、bundle releaseType）。
• バンドル暗号化を設定する場合（key create、key save、--key-v2）。

次の場合は使用しないでください。

• アプリ側のアップデーターコードまたは設定（notifyAppReady、autoUpdate、setChannel）に関する作業。capgo-live-updates を使用してください。
• ネイティブバイナリが必要な場合。capgo-native-builds を使用してください。
• ユーザーが組織、メンバー、2FA、または API キーポリシーを管理する場合。capgo-organization-management を使用してください。
• ユーザーがエンドツーエンドのリリースパイプラインの設計を希望する場合。capgo-release-workflows を使用してください。

コマンド一覧

目的	コマンド
アップロードしてリンク	bundle upload [appId] --path ./dist --channel production（複数のチャネルはカンマ区切り）
OTA セーフかどうかを確認	bundle releaseType [appId] --channel production は OTA または native を出力します
ネイティブの詳細な差分	bundle compatibility [appId] --channel production [--text]
現在の配信内容	channel currentBundle production [appId] --quiet
昇格	channel promote staging production [appId]
ロールバック	channel set production [appId] --bundle <previous-version>
ロールアウト	bundle upload ... --rollout 10、続けて channel set ... --rollout-percentage 50 / --rollout-promote / --rollout-rollback
チャネルを作成	channel add beta [appId] [--default] [--self-assign]
チャネルポリシー	channel set <ch> --disable-auto-update major|minor|patch|metadata|none と --ios/--android/--dev/--prod/--emulator/--device の切り替え
一覧表示	bundle list [appId]、channel list [appId]
クリーンアップ	bundle cleanup [appId] --bundle 1.0 --keep 3
削除	bundle delete <version> [appId]、channel delete <ch> [appId]
プレビュー QR	一度だけ app set [appId] --preview を実行し、その後 get-qr [appId] --channel beta または bundle upload ... --qr-preview
暗号化キー	key create、key save --key ./.capgo_key_v2.pub、key delete_old
カスタム zip／外部	bundle zip [appId] --json、bundle encrypt <zip> <checksum>、bundle upload --external <url>

これらはすべて npx @capgo/cli@latest <command> で実行します。存在しないコマンド（古いドキュメントや他のツールに由来するもの）は、channel create、bundle revert、upload --sign、key verify、および bundle を伴わないトップレベルの capgo upload です。

手順

1. まず確認する

npx @capgo/cli@latest channel list com.example.app
npx @capgo/cli@latest channel currentBundle production com.example.app --quiet
npx @capgo/cli@latest bundle releaseType com.example.app --channel production

変更を加える前に、現在の配信バージョンと OTA／ネイティブの判定結果を報告してください。判定結果が native の場合は作業を中止し、capgo-native-builds（またはユーザーのネイティブパイプライン）に引き継いでください。

2. アップロードする

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel staging --comment "$(git rev-parse --short HEAD)"

• バージョンは --bundle <semver> を指定しない限り package.json から取得されます。一意で、0.0.0 より大きく、過去に削除されたバージョンであってはなりません。
• 即時適用アプリでは --delta を使用してください。CLI はファイル数が 10,000 を超えるデルタアップロードを拒否します。その場合は --no-delta を使用してください。
• CI では --fail-on-incompatible を使用してください。--accept-incompatible を使用するのは、JavaScript 側で不足しているプラグインをガードする場合に限ってください。これら 2 つのフラグは --ignore-metadata-check と併用できません。

3. プロモーションとロールアウト

• プロモーション：npx @capgo/cli@latest channel promote staging production com.example.app。channel set --bundle と同じ互換性チェックが実行されます。
• 段階的なロールアウト：--rollout <pct> を指定してアップロードし、--rollout-promote を実行する前に統計を確認します。
• ユーザーが本番トラフィックの移行を明示的に希望している場合に限り、どのチャンネルをデフォルトにするか変更してください（channel set <ch> --state default または channel add --default）。

4. ロールバック

npx @capgo/cli@latest bundle list com.example.app
npx @capgo/cli@latest channel set production com.example.app --bundle 1.4.2
# or, during a rollout:
npx @capgo/cli@latest channel set production com.example.app --rollout-rollback

デバイスは次回のアップデート確認時に変更を適用します。

5. 暗号化（オプション、機密性の高いアプリ向け）

npx @capgo/cli@latest key create        # writes .capgo_key_v2 (private) + .capgo_key_v2.pub, saves the public key to config
npx cap sync                             # the public key must ship in the native app
npx @capgo/cli@latest bundle upload com.example.app --key-v2 ./.capgo_key_v2 --channel production

CI では、秘密鍵を CI のシークレットストアに保管し、ジョブ内で ./.capgo_key_v2 に書き込み、同じ --key-v2 ./.capgo_key_v2 を指定します。秘密鍵がランナーの外に出ることはありません。.capgo_key_v2 を .gitignore に追加し、絶対にコミットしないでください。鍵を変更する場合は、新しいネイティブビルドが必要です。古い publicKey を持つデバイスでは key_id_mismatch が発生します。

注意点

• ロールアウトが設定されているチャンネルで、通常の bundle upload --channel production を実行すると、ロールアウトのターゲットが設定され、安定版は変更されません。安定版を置き換えるには、明示的に channel set --bundle を使用してください。
• bundle cleanup --ignore-channel は関連付けられたチャンネルも削除します。確認せずに追加しないでください。
• bundle delete は取り消せず、削除したバージョンは再利用できません。ロールバックには、以前のバンドルを再リンクする方法を優先してください。
• releaseType が確認するのはネイティブパッケージのメタデータのみで、ios/ や android/ の生の編集内容は確認しません。
• アップロード時の --self-assign は、このバンドルだけでなくチャンネルの設定を変更します。

検証

1. npx @capgo/cli@latest channel currentBundle production com.example.app --quiet を実行すると、想定したバージョンが出力されます。
2. プロジェクト内で npx @capgo/cli@latest probe --platform ios を実行すると、アップデートが配信されるかどうかが報告されます。
3. npx @capgo/cli@latest app debug com.example.app で、テストデバイスがバンドルをダウンロードして設定する様子を確認できます。
4. 暗号化されたアップロードの場合、新しいネイティブビルドを使用するデバイスで、key_id_mismatch エラーが発生せずにアップデートが適用されることを確認します。

エラー処理

文字列	修正方法
❌ Version X already exists	--bundle の値を増やすか、--auto-bump patch を使用するか、CI の再実行時に --version-exists-ok を渡します
Cannot upload the same bundle content	チェックサムはすでにそのチャンネルにあります。変更を加えて再ビルドするか、--ignore-checksum-check を渡します
Bundle NOT compatible with <channel> channel	ネイティブパッケージが異なります。先にネイティブビルドを行うか、コードで保護されている場合は --accept-incompatible を使用します
notifyAppReady() is missing in the build folder (...)	アプリのエントリーポイントを修正してください（capgo-live-updates を参照）
index.html is missing in the root folder of <dir>	--path の指定が間違っています
Cannot find channel <name>	channel list を確認してください。名前の大文字と小文字は区別されます
Channel strategy <x> is not known	major、minor、patch、metadata、または none を使用します
No Capgo API key found. Run ... first, then retry this command.	npx @capgo/cli@latest login を実行するか、CAPGO_TOKEN を設定するか、-a を渡します
Insufficient permissions for <key>	API キーのロールでは、このアプリに対する権限が不足しています。アップロード権限のあるキーを管理者に依頼してください
Cannot upload bundle ( try again with --tus option)	--tus を指定して再試行し、大きなバンドルの場合は --timeout を増やします

リソース

• バンドルのリファレンス：https://capgo.app/docs/cli/reference/bundle/
• チャンネルのリファレンス：https://capgo.app/docs/cli/reference/channel/
• 段階的ロールアウト：https://capgo.app/docs/live-updates/progressive-rollouts/
• 暗号化：https://capgo.app/docs/live-updates/encryption/
• 互換性：https://capgo.app/docs/live-updates/compatibility/