Native + OTA チャンネルのワークフロー

一般的な Capgo の構成では、 dev チャンネルと 本番 チャンネルを使用します。CIはすべてのOTA bundleを devにアップロードし、準備ができたら production へ昇格させます。チームはよく --fail-on-incompatible を追加して、新しいnative code が必要な live update をCIが誤ってリリースしないようにします。

このページでは、以下の疑問に答えます： 以下の状況ではどうすればよいでしょうか？ 意図的に 現在のチャンネルのネイティブパッケージと互換性のないbundleが必要な場合です。

Capgo がネイティブパッケージを比較する理由について詳しく知りたい場合は、まずこちらをご覧ください。 ネイティブ互換性OTA と Capgo Build を自動的に切り替える完全な CI ブランチについては、以下を参照してください。 OTA / Native 自動切替.

推奨されるチャンネル構成

このガイドでは、 dev と production チャンネルが既に存在することを前提としています。必要に応じて、先に作成してください。

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

チャンネル	対象ユーザー	一般的なアップロード
dev	社内 / QAビルド	JSのCIプッシュ時（および意図的なNative Buildのベースライン時）
production	ストアのユーザー	リリース準備が整った時のみ昇格またはアップロード

--fail-on-incompatible の両方のチャネルにおいて、以下の用途のデフォルトとして適しています： 日常的なOTAアップロード。アップロードするバンドルのネイティブパッケージを、既存のバンドルと比較します。 現在そのチャンネルで公開中. 不一致の場合、uploadは非ゼロで終了し、何もデプロイされません。

Everyday OTA (フラグを維持)

変更がJavaScriptのみで、ネイティブパッケージがチャンネルと一致する場合：

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible 意図しないネイティブコードの乖離を防ぎます。 --auto-min-update-version を使用するチャネルでは、すべてのアップロード時に必須になります。 metadata ストラテジー（以下で推奨）のことです。チャネルがまだ metadata そのストラテジーを使っていない場合は、省略できます。 --auto-min-update-version 切り替えるまでは省略できます。

upload前のオプションのCIゲート:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

意図的なNative Bump（一度フラグを外す）

お客様 できません 新しいNative codeが必要なbundleをuploadすることは、 --fail-on-incompatibleその状態を維持したままでは不可能です。そのフラグはまさにそのケースを防ぐために存在します。プラグインやCapacitorのバージョン、その他のNative依存関係を意図的に変更した場合は：

1. 対応する ネイティブバイナリ (App Store / Play Store、または Capgo のビルド).
2. 対応するJS bundleをアップロードし、 なしで --fail-on-incompatible.
3. 推奨： --auto-min-update-version チャンネルを metadata strategyに設定することで、古いバイナリのままのデバイスが新しいアプリをインストールするまで新しいbundleを受信しないようにします。
4. そのベースラインアップロードの後、 --fail-on-incompatible 通常のOTA CIに戻す（そして --auto-min-update-version チャンネルがオンの間はそのままに metadata).

1. チャンネルごとに1回：metadata gatingを有効にする

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

   以下を繰り返します： dev そのチャンネルに意図的な Native Build も配信する場合。この切り替え後は、そのチャンネルへのすべての upload に以下を含める必要があります： --auto-min-update-version または --min-update-version.

2. Native Binary をリリースする

   新しいプラグインやネイティブの変更を含む iOS/Android アプリをビルドして提出します。ユーザーがそのバイナリをインストールするまで、それらのネイティブパッケージに依存する bundle を安全に実行することはできません。

3. 対応する OTA baseline を upload する（ --fail-on-incompatible)

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --auto-min-update-version

   これにより、チャンネルに新しいネイティブパッケージが記録されます。その後、 bundle releaseType / --fail-on-incompatible がその baseline を使用してチェックを行います。

4. 保護された OTA upload を再開する

   その後の JS のみのリリースでは、再び両方のフラグを使用します：

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --fail-on-incompatible \
     --auto-min-update-version

ヒント

native-baseline のアップロードは、 専用の CI ジョブ (または手動のリリースステップ) として扱いましょう。デフォルトの OTA ジョブに例外として混ぜるのではなく、デフォルトのジョブは常に、 --fail-on-incompatible、そして metadata チャネルにおいても、常に、 --auto-min-update-version.

よくある質問

継続できますか？ --fail-on-incompatible それでもネイティブ互換性のないbundleをpushできますか？

いいえ。アップロードするネイティブパッケージが、そのチャンネルのlive bundleと異なる場合、このフラグによってコマンドは意図的に失敗します。意図的にネイティブ構成を変更する場合は、そのアップロード時のみフラグを外してください（そして、 --auto-min-update-version 可能な限りフラグを使用してください）。

フラグなしで一度だけアップロードするのが正しい方法ですか？

はい。新しいバイナリをリリースした後に、チャンネルのネイティブベースラインを進めるためのサポートされている方法です。それ以外のOTAアップロードでは常にフラグを有効にしておき、意図しないネイティブ構成の乖離（drift）が発生した際にCIが失敗するようにしてください。

どこにアップロードすればいいですか？ dev を行いますか？ production?

はい、それがあなたのワークフローに合致しているなら、その通りです。同じルールを チャンネルごとに適用してください。: 互換性チェックは、対象の channel で現在 live になっているものに対して行われます。以下のいずれかを行ってください：promote または再アップロード production 〜した後にのみ dev 問題なさそうであれば、native-baseline upload を使用してください（ --fail-on-incompatible）。新しい native packages の記録が必要な各 channel に対して行います。

フラグをオンにしたまま、新しい native bundle を upload したらどうなりますか？

CI が失敗し、Capgo はその upload をリリースしません。これは想定通りの動作です。変更が accidental であった場合（native packages を修正して OTA として再試行）、または intentional であった場合（上記の native パスを使用）のいずれかです。

どの job にどのフラグを設定すべきですか？

パス	次の場合:	アップロードフラグ
OTA	JSのみ。ネイティブパッケージはチャンネルと一致	--fail-on-incompatible + --auto-min-update-version (チャンネルが以下の場合に必要) metadata)
Native baseline	新しいNative Build + 対応するJS bundle	いいえ --fail-on-incompatible; 維持 --auto-min-update-version

関連情報

ネイティブ互換性

Capgo がネイティブパッケージの乖離をどのように検出し、「互換性なし」がデバイスにどのような影響を与えるかについて。

OTA / Native 自動切替

連携 bundle releaseType GitHub ActionsやGitLabに組み込み、CIが正しいパスを選択できるようにします。

バージョンターゲティング

Channel、semverルール、およびデリバリーフロア用のメタデータ戦略。

CLI: bundle

upload、compatibility、releaseType、および関連フラグのリファレンス。

Native + OTA Channel Workflowの次のステップ

使用している場合 Native + OTA チャンネルのワークフロー Nativeリリース間でLive Updateの安全性を保つには、以下と連携させます ネイティブ互換性 パッケージ比較ルール、 OTA / Native 自動切替 CIブランチング、 バージョンターゲティング メタデータの閾値、および Capgo CLI bundleリファレンスは アップロードフラグ用。