capgo-native-builds

Capgo ネイティブビルド

Capgo Cloud Build で署名済みの iOS および Android バイナリをビルドし、ストアまたは一時ダウンロードリンクに配信します。

以下の情報は、@capgo/cli 8.77 および https://capgo.app/docs/builder/ を基に確認済みです（2026 年 10 月）。CLI では、ネイティブのクラウドビルドは「限定ベータ」と説明されています。

使用する場面

次の場合に使用します。

• ユーザーが Capgo Cloud Build、クラウドでのネイティブビルド、署名済み IPA／APK／AAB、Capgo 経由での TestFlight、App Store、Play へのアップロード、一時的なビルドのダウンロードリンクや QR コードについて尋ねた場合。
• ユーザーが build init、build request、build prescan、build needed、build last-output、build sync-ios-version、または build credentials ... サブコマンドを実行したり、質問したりした場合。
• Capgo のビルドで、署名、プロビジョニング、キーストア、事前スキャン、ストアへのアップロードに関するエラーが発生した場合。

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

• JavaScript／Web アセットだけを変更する場合。これは OTA リリースです。capgo-release-management を使用してください。プラグインの配線には capgo-live-updates を使用してください。
• ユーザーが Xcode または Gradle でローカルビルドを行う場合、あるいは Capgo Build を使わずに独自の CI ランナーでビルドする場合。capacitor-ci-cd を使用してください。
• ユーザーがストアの掲載情報、メタデータ、審査の準備を必要としている場合。capacitor-app-store および capacitor-apple-review-preflight を使用してください。
• ユーザーが Capacitor 自体をアップグレードする場合。capacitor-app-upgrades を使用してください。

リファレンス一覧

トピックが該当する場合にのみ、リファレンスを読み込んでください。

ファイル	読み込むタイミング
references/request-options.md	ストアへの提出、トラック、リリースノート、バージョン管理、キャッシュ、Xcode のバージョン、事前スキャンのフラグなど、build request の具体的なフラグを指定するとき
references/credentials-and-ci.md	認証情報の保存、更新、エクスポート、移行、および CI のシークレットへの登録を行うとき

シークレットと確認

• Capgo API キー、署名パスワード、.p8 キー、キーストア、サービスアカウント JSON をチャットに貼り付けるよう、ユーザーに求めないでください。ユーザー自身に npx @capgo/cli@latest login を実行してもらってください（ブラウザーが開くか、マスクされたプロンプトでキーの入力を求められます）。または、シェルか CI のシークレットストアに CAPGO_TOKEN を設定してもらってください。
• シークレットをコマンド引数に指定しないでください。シェルの履歴やプロセス一覧に残ります。環境変数、保存済みログイン情報、または CLI の対話型プロンプトを使用してください。
• それでもシークレットが会話に含まれてしまった場合は、繰り返したりファイルに書き込んだりせず、ユーザーに失効させて新しいものを作成するよう伝えてください。
• npx @capgo/cli@latest は npm から最新の CLI をダウンロードして実行します。ユーザーのプロジェクト内で、ユーザーの許可を得てからのみ実行してください。CI では、正確なバージョンを固定してください。
• リモートの状態を変更するコマンドを実行する前に、必ず確認してください。対象には、バンドルのアップロード、チャンネルの変更または昇格、アプリ・バンドル・チャンネル・キーの削除、ストアにアップロードするビルドのリクエスト、認証情報のエクスポートまたは削除が含まれます。対象のアプリとチャンネルについて、何が変更されるかを伝えてください。

運用ルール

• ユーザー向けのコマンドでは npx @capgo/cli@latest を使用してください。
• API キー、P12 パスワード、キーストアのパスワード、.p8 キー、Play のサービスアカウント JSON はシークレットです。例ではプレースホルダーを使用してください。チャットでユーザーに尋ねたり、受け取った値をそのまま返したりしないでください。チャットに貼り付けられた場合は、失効させて新しいものを作成するよう伝えてください。
• 認証情報はローカルに保存されます（~/.capgo-credentials/credentials.json、または --local を指定した場合は .capgo-credentials.json）。ビルドジョブでのみアップロードされ、一時的なサーバー上のコピーはビルド完了時に削除されます。どちらのファイルもコミットしないでください。
• ビルドをリクエストする前に、プラットフォーム、アプリ ID、プロジェクトのパス、フレーバーまたはスキーム、配信先（ストアへのアップロード、ダウンロードリンク、または両方）を確認してください。

認証と API キーの優先順位

CLI は次の順序でキーを解決します。

1. コマンドの -a, --apikey <key>
2. CAPGO_TOKEN 環境変数
3. npx @capgo/cli@latest login で保存したグローバルキー ~/.capgo
4. login --local で保存したプロジェクトキー ./.capgo

注意：グローバルキーはプロジェクトローカルのキーより優先されます。リポジトリで別の組織のキーを使用する必要がある場合は、CAPGO_TOKEN を設定してください。.capgo が Git の対象外になっていることを確認してください。

手順

1. 確認

• ls ios android を実行し、対象のネイティブフォルダーが存在することと、npx cap sync <platform> が実行済みであることを確認します。
• capacitor.config.* の appId を確認します。iOS のバンドル ID および Android の applicationId と一致している必要があります（prescan チェック shared/bundle-id-consistency）。
• iOS：Xcode のスキーム名とターゲット名（デフォルトは App）、および個別のプロビジョニングプロファイルが必要な拡張機能を確認します。
• Android：android/app/build.gradle の productFlavors を確認します。フレーバーが複数ある場合は、--android-flavor が必要です。
• アプリが存在することを確認します：npx @capgo/cli@latest app list。npx @capgo/cli@latest app add com.example.app で追加します。

2. そもそもネイティブビルドが必要かどうかを判断する

npx @capgo/cli@latest build needed com.example.app --channel production
# prints "yes" and exits 1 -> native build required
# prints "no" and exits 0 -> ship OTA instead
# exits 2 -> the command itself failed

ネイティブパッケージのメタデータのみを比較します。ios/ または android/ 内の生の編集には、引き続きネイティブビルドが必要です。

3. 認証情報を設定する

初回ビルドは対話形式（推奨）：

npx @capgo/cli@latest build init        # alias: build onboarding

• iOS：App Store Connect API キーを検証または作成し、その後、証明書、バンドル ID、App Store プロビジョニングプロファイルを作成または再利用します。すべてをローカルに保存し、初回ビルドを開始できます。進行状況は ~/.capgo-credentials/onboarding/ に保存されるため、後から再開できます。
• Android：キーストアを設定します。その後、Google OAuth により GCP サービスアカウントがプロビジョニングされ、Play Console の招待が送信されます。
• .p8 キー用の macOS ヘルパー：npx @capgo/cli@latest build credentials apple-key --appId com.example.app。

署名ファイルがすでにある場合は、代わりに build credentials save を使用します。references/credentials-and-ci.md を参照してください。

4. 事前チェック

npx @capgo/cli@latest build prescan com.example.app --platform ios

prescan は build request 内で自動的に実行されます。アップロードを始める前に問題を修正するには、単独で実行してください。意図的な検出結果がある場合は、該当するチェックのみをスキップします：--prescan-skip <check-id>。--no-prescan は使用しないでください。

5. ビルドをリクエストする

# App Store / TestFlight (default ios distribution app_store)
npx @capgo/cli@latest build request com.example.app --platform ios --path .

# Android to Play internal track (default track internal, status draft)
npx @capgo/cli@latest build request com.example.app --platform android --path .

# Artifact only, no store upload
npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload --output-retention 2d
npx @capgo/cli@latest build request com.example.app --platform android --no-playstore-upload --output-upload

--output-retention の範囲は 1h から 7d です。認証情報に保存されるデフォルト TTL は 1h です。

注意点

• Xcode／Capacitor 9： Capgo Build のドキュメントには、Xcode 26.2 を搭載した macOS Tahoe 26.2 が記載されています。--xcode-version <major[.minor]>（または CAPGO_IOS_XCODE_VERSION）でバージョンを固定できます。Capacitor 9 には Xcode 27 以降が必要です。Capgo のドキュメントと CLI 8.77 では、Xcode 27 のビルダーが確認されていません。Capacitor 9 の iOS クラウドビルドを約束する前に、--xcode-version 27 を指定するか、最新のドキュメントを確認してください。
• --no-playstore-upload には --output-upload が必要です。そうしないと、ビルドの出力先がありません。
• アドホック iOS ビルドはストアへのアップロードをスキップします。App Store のレコードがまだ存在しない場合は、--output-upload と併用してください。
• --submit-to-store-review を指定すると、Android のデフォルトが production トラック、ステータス completed に変更されます。追加する前にユーザーに確認してください。
• ビルド番号はデフォルトで自動的にインクリメントされます。ビルド番号をプロジェクト側で管理している場合は、--skip-build-number-bump を追加してください。マーケティングバージョンも自動で引き上げられることがあります（--skip-marketing-version-bump で無効にできます）。
• ビルドのタイムアウトはデフォルトで 15 分です。npx @capgo/cli@latest app set com.example.app --build-timeout-minutes 60 で延長できます（範囲は 5～360 分）。
• capacitor.config に server.url が残っている場合（ライブリロード）、ストア向けビルドでは prescan の ios/capacitor-server-url-shipped に失敗します。チェックをスキップするのではなく、削除してください。

検証

1. npx @capgo/cli@latest build credentials list --appId com.example.app に、対象プラットフォームのマスク済み認証情報が表示されます。
2. npx @capgo/cli@latest build prescan com.example.app --platform <p> --fail-on-warnings が終了コード 0 で終了します。
3. build request が成功ステータスで終了します。--output-upload を指定すると、ダウンロードリンクと QR コードが表示されます。--output-record /tmp/build.json を指定した場合は、npx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl を確認してください。
4. ストアへのアップロード経路：選択した TestFlight または Play Console のトラックにビルドが表示されます。
5. 成果物をデバイスにインストールし、バージョンとビルド番号を確認します。

エラー処理

文字列／症状	対処方法
No Capgo API key found. Run ... first, then retry this command.	ユーザーは npx @capgo/cli@latest login を実行するか、CAPGO_TOKEN を設定します
<key> に対する Insufficient permissions for <key> ／ prescan shared/apikey-permission	キーのロールでは、このアプリまたは組織のネイティブビルドをリクエストできません。ビルド権限のあるキーを使用してください
Missing required argument: --platform <ios|android>	--platform ios または --platform android を追加してください
❌ No credentials found for this app and platform	build init または build credentials save --appId <id> --platform <p> ... を実行してください。--local とグローバルストアのどちらを使っているか確認してください
Legacy provisioning profile format detected. Run: npx @capgo/cli build credentials migrate --platform ios	npx @capgo/cli@latest build credentials migrate --platform ios を実行してください
Missing argument, you need to provide a appId, or be in a capacitor project	アプリ ID を位置引数で渡すか、アプリのルートから実行してください
output-retention must be a number with optional unit: s, m, h, d	1h、6h、2d などを使用してください（最大 7d）
prescan ios/cert-profile-pairing ／ ios/profile-type-vs-mode	プロファイルに証明書が含まれていないか、app_store／ad_hoc と一致していません。build credentials ios-provisioning で再生成してください
prescan ios/targets-covered	拡張機能にプロファイルがありません。--ios-provisioning-profile <bundleId>=<path> を追加してください
Android の「Key alias not found」／パスワードが違う	エイリアスとパスワードを確認してください。異なる場合は、--keystore-key-password と --keystore-store-password の両方を渡してください
複数のフレーバーに関するエラー	--android-flavor <flavor> を追加してください
原因を調べる場合	--verbose を付けて再実行してください。--ai-analytics は失敗ログを Capgo AI に送信します。--send-logs-to-support はサポートにログを送信します

その他の対処方法：https://capgo.app/docs/builder/troubleshooting/

関連ドキュメント

• ビルドのリファレンス：https://capgo.app/docs/cli/reference/build/
• はじめに：https://capgo.app/docs/builder/getting-started/
• iOS：https://capgo.app/docs/builder/ios/ · Android：https://capgo.app/docs/builder/android/
• 認証情報：https://capgo.app/docs/builder/credentials/ · prescan：https://capgo.app/docs/builder/prescan/
• CI での OTA とネイティブビルド：https://capgo.app/docs/builder/ci-ota-or-native/