capgo-release-workflows

Capgo リリースワークフロー

エンドツーエンドのリリースシステムを構築します。Web の変更には Capgo OTA、バイナリーの変更にはネイティブビルド、ストアへの公開、そして適切な経路を選択する CI ゲートを組み合わせます。

使用する場面

次の場合に使用します。

• ライブアップデート、ネイティブビルド、ストアへの公開を網羅する単一のリリースパイプラインをユーザーが求めている場合。
• ユーザーがホスト型リリースサービス（Appflow 形式）から、自社で管理する CI に移行する場合。
• ユーザーが「これにストアリリースが必要かどうかを CI はどう判断するのか」と尋ねている場合。

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

• ユーザーが単一の操作（バンドルのアップロードまたは昇格、ビルドのリクエスト）を必要としている場合。capgo-release-management または capgo-native-builds を使用してください。
• ユーザーがアップデータープラグインを接続しようとしている場合。capgo-live-updates を使用してください。
• ユーザーが Ionic Appflow からの移行を具体的に進めている場合。まず ionic-appflow-migration を使用し、その後、パイプラインについてここに戻ってください。
• アプリが Capacitor ではない場合。

構成要素

領域	スキル	主なコマンド
OTA アップデート	capgo-live-updates、capgo-release-management	bundle upload、channel promote
Capgo でのネイティブビルド	capgo-native-builds	build request
自社ランナーでのネイティブビルド	capacitor-ci-cd	Xcode／Gradle／Fastlane
ストアのリスティングと審査	capacitor-app-store、capacitor-apple-review-preflight	該当なし

手順

1. 現状を確認する（調査してから報告）

以下を確認します。

• 実行している CI システム（.github/workflows、.gitlab-ci.yml、bitbucket-pipelines.yml、azure-pipelines.yml）。
• @capgo/capacitor-updater が @capacitor/core と同じメジャーバージョンでインストールされているか、また notifyAppReady() が呼び出されているか。
• 既存の Capgo チャネル（npx @capgo/cli@latest channel list <appId>）とデフォルトチャネル。
• ネイティブ署名情報の保存先（Capgo の認証情報、CI のシークレット、Fastlane match）。
• ストアへのアップロードが必要か、それとも内部配布のみか。

不足している点をユーザーに報告し、ネイティブビルドに Capgo Build と自社ランナーのどちらを使うか、選択する前に確認してください。

2. チャネルとバージョン管理を定義する

• 一般的なチャネル：development（自己割り当て）、staging、production（デフォルト）。
• バンドルのバージョンには semver を使用します。CI では --bundle <ver> または --auto-bump patch と、--version-exists-ok を使用します。
• 本番環境ではメタデータ戦略を一度設定し、アップロードのたびにネイティブの基準バージョンが記録されるようにします。

npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

3. OTA とネイティブを切り替えるゲートを追加する

# After npm ci && npm run build
if git diff --name-only "$BASE" HEAD | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
  TYPE=native
else
  TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]')
fi

releaseType はネイティブパッケージのメタデータから OTA または native を出力します。生のネイティブコードの編集は検出できないため、git のパスチェックも必要です。build needed は終了コードで判定するバージョンです。終了コード 1 はネイティブビルドが必要、終了コード 0 は OTA で問題なし、終了コード 2 はコマンドの失敗を示します。

4. 両方の経路を接続する

• OTA： bundle upload --channel staging --fail-on-incompatible --auto-min-update-version を実行し、その後、手動または承認を経て channel promote staging production を実行します。必要に応じて --rollout 10 を指定します。
• ネイティブ： build request --platform ios|android（Capgo Build）またはネイティブジョブを実行し、その後 --auto-min-update-version を指定して対応するバンドルをアップロードし、チャネルの基準バージョンを更新します。この基準バージョンのアップロードでは、--fail-on-incompatible を指定しないでください。ネイティブパッケージは異なることが前提だからです。

GitHub Actions および GitLab のテンプレート全文：https://capgo.app/docs/builder/ci-ota-or-native/

5. ロールバック計画（最初のリリース前に文書化する）

• OTA：channel set production --bundle <previous> または --rollout-rollback。--auto-pause-enabled --auto-pause-action rollback を指定すると、自動一時停止が有効になります。
• ネイティブ：ストアではロールバックできません。修正版をリリースし、Web レイヤーに OTA パッチを適用できる状態にしておいてください。

6. シークレット

• CAPGO_TOKEN（アップロード権限を持つ、最小権限のトークン）と、バンドルを暗号化する場合は CAPGO_PRIVATE_KEY。
• ネイティブ署名：build credentials manage → .env で Capgo からエクスポートし、その後 gh secret set -f を実行します。または既存の CI シークレットストアを使用します。
• .capgo、.capgo_key_v2、.capgo-credentials.json、.env.capgo.* は絶対にコミットしないでください。

検証

エンドツーエンドで1回実行します。

1. ウェブのみのコミットでOTAブランチに進みます。ステージング環境のデバイスにバンドルが配信されます（npx @capgo/cli@latest app debug <appId>）。
2. ネイティブプラグインを追加またはアップグレードするコミットで、ネイティブブランチに進みます。ビルドが成功し、TestFlightまたはPlayの内部テストトラックに反映されます。
3. ネイティブリリース後、ウェブのみの変更に対してbundle releaseType --channel productionを実行すると、再びOTAが返されます。
4. ロールバックの練習（channel set --bundle <previous>）で、テストデバイスに変更が反映されます。

エラー処理

• CIのアップロードがNo Capgo API key foundで失敗する場合：CAPGO_TOKENがステップのenvにエクスポートされていません。
• OTAブランチでBundle NOT compatible with production channelが表示される場合：ゲートがスキップされたか、releaseTypeが別のチャネルに対して実行されています。
• 署名エラー：パイプラインのロジックに手を加える前に、まず認証情報を修正します（capgo-native-builds、build prescan）。
• ストアのエラー：一方のプラットフォームの問題がもう一方の診断を妨げないよう、iOSとAndroidのジョブを分割します。

リソース

• CIでのOTAまたはネイティブ：https://capgo.app/docs/builder/ci-ota-or-native/
• CI/CD統合：https://capgo.app/docs/getting-started/cicd-integration/
• Capgo Build GitHub Actions：https://capgo.app/docs/builder/github-actions/
• ネイティブ＋OTAチャネルのワークフロー：https://capgo.app/docs/live-updates/native-ota-channel-workflow/