GitHub アクション

インストール手順と、このプラグインの完全なMarkdownガイドを含むセットアッププロンプトをコピーします。

GitHub リポジトリから、iOS と Android のビルドを直接自動化しましょう。1つのワークフローファイルといくつかのリポジトリ Secret を設定するだけで、push、tag、または手動トリガーごとに、署名済みのストア公開用アプリを生成できます。チームメンバーが Mac や Xcode、Android Studio をインストールしておく必要はありません。

簡潔に言うと： GitHub Actions 上で Capacitor の CI/CD を実現するには、Capgo CLI を実行するワークフローを1つ追加するだけです。Capgo Builder が署名済みの iOS および Android ビルドを生成し、ストアへ upload することができ、さらに bundle upload ジョブを追加することで（詳細は OTA / Native 自動切替）、同じワークフローで Web の変更のみを Capgo Live Update として配信できます。

メリット

ハンズオフなリリース

Git でリリースをタグ付けするだけで、署名済みの iOS および Android バイナリが TestFlight や Play Store へ自動的に送信されます。

ローカル環境の構築不要

WindowsやLinuxのコントリビューターでもiOSビルドを実行できます。Xcodeやプロビジョニング、証明書の共有といった煩わしい作業は一切不要です。

スコープ付きのSecrets

認証情報はGitHubリポジトリのSecretsに保存され、リポジトリ内に限定してワークフローランナーのみがアクセス可能です。ローテーションや監査も簡単に行えます。

並列ビルド

マトリックスジョブを使用してiOSとAndroidを同時にビルドできます。標準的なリリースなら10分以内に完了します。

前提条件

ワークフローを設定する前に、以下を確認してください：

有効なサブスクリプション付きの Capgo アカウントと、 Capgo API キー
Capgo に登録済みのアプリ（bunx @capgo/cli@latest app add 未登録の場合）
ローカルで設定済みの Build credentials（ bunx @capgo/cli@latest build init — 下記の「認証情報の管理ウィザードのチュートリアル用）
ローカルでのビルド成功実績（bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CIは最初のビルドをデバッグする場所ではありません
この GitHub CLI (gh) インストールと認証が済んでいる (gh auth login)

セットアップ

Capgo CLI は、ローカルの認証情報をそのまま使える .env ファイルとしてエクスポートできます。これに gh secret set -fこれにより、CI/CD設定全体がわずか3つのコマンドに集約されます。手動でのbase64エンコードやJSONの操作、シークレットを一つずつコピー＆ペーストする手間はもう必要ありません。

Capgo API キーをリポジトリのSecretとして追加してください

API キーはアプリごとの認証情報ストアには含まれないため、一度だけ手動で追加してください：
ターミナル
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
キーの生成は Capgo dashboard で行えますを使用して アップロード 以上の権限が必要です。
認証情報を以下にエクスポートします： .env ファイル

対話型の認証情報マネージャーを実行します：
ターミナル
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
TUIで以下を選択してください： .envへエクスポート. CLI は、 .env.capgo.<appId> 現在のディレクトリに mode モードで書き込みます 0600 （所有者のみが閲覧可能）— 例： .env.capgo.com.example.appiOSとAndroidの両方が設定されている場合、両プラットフォームのシークレットは以下のパスにある同じファイルに保存されます。 # === IOS === と # === ANDROID === セクションヘッダーに分かれます。iOSとAndroidの環境変数名は重複しないため、統合しても競合は発生しません。

渡す --platform ios (または --platform android) を指定することで、マネージャーを特定のプラットフォームに限定できます。エクスポートすると、以下のようにプラットフォームごとのファイルが生成されます。 .env.capgo.com.example.app.iosiOSとAndroidのシークレットが異なるリポジトリや環境にある場合に便利です。

いくつかの設定トグル（BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION）はプラットフォームごとに個別に保存されており、設定が乖離している場合があります。マネージャーが乖離を検知すると、競合しているキーを表示して書き込み前に明示的な確認を求め、競合リストをファイルの先頭にコメントとして埋め込みます。プラットフォームごとの値を保持する必要がある場合は、 --platform で再エクスポートしてください。
を .env ファイルとして GitHub Actions secrets にプッシュしてください。

この gh secret set -f コマンドは dotenv ファイルを読み込み、各 KEY=value 行に対して
ターミナル
```
gh secret set -f .env.capgo.com.example.app
```
これで完了です。ワークフローに必要なすべてのシークレットが GitHub に設定されました。以下で確認してください： gh secret list.
.env ファイルはコミットしないでください
ここには平文の署名情報が含まれています。一度 GitHub にプッシュしてしまうと：
ターミナル
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
認証情報のローテーションが必要なときはいつでも再エクスポートしてください。このファイルは永続的に保持するものではありません。
ワークフローファイルを作成する

追加 .github/workflows/capgo-build.yml リポジトリに追加します。ビルドの実行タイミングに合わせて、以下の3つのトリガーパターンのいずれかを選択してください。

Secrets に保存される内容

参考： gh secret set -f 以下のリポジトリ Secret が作成されます（ワークフローの YAML では、これらの名前で直接参照してください）：

プラットフォーム	作成されたSecrets
iOSと	`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `CAPGO_IOS_PROVISIONING_MAP_BASE64`, `APPLE_KEY_ID`, `APPLE_ISSUER_ID`, `APPLE_KEY_CONTENT`, `APP_STORE_CONNECT_TEAM_ID`
Androidでは	`ANDROID_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
(手動で追加)	`CAPGO_TOKEN`

これらを暗記する必要はありません。以下のワークフロー例ですべて参照しています。

ワークフローの例

以下の3つの例は、最も一般的なパターンをカバーしています。すべて共通の構成です：リポジトリのチェックアウト、依存関係のインストール、Webアセットのビルド、ネイティブへの同期、そして環境変数として渡された認証情報を使用して Capgo Build を実行します。

1. 手動トリガー

書き込み権限を持つユーザーなら誰でも、以下からビルドを実行できます。 アクション プラットフォームのドロップダウンがある GitHub のタブです。アドホックなテストビルドや、オンデマンドでのリリース実行に便利です。

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync

      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

置換する com.example.app アプリIDを指定します。コミット後、 Actions → Capgo Build (Manual) → workflowを実行 から実行できます。

2. タグによるリリース

バージョンタグをプッシュするたびに、両方のプラットフォームを並列でビルドして配信します。例： v1.4.0. これは最も一般的な本番環境のセットアップです — git tag v1.4.0 && git push --tags がリリースコマンドになります。

name: Capgo Build (Release)

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}

      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          # Android
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

Matrixを使用することで、iOSとAndroidを別々のランナーで並列実行します。\n fail-fast: false を設定すると、iOSのビルドが失敗しても進行中のAndroidビルドを中断させません（その逆も同様）。片方のプラットフォームで一時的な署名エラーが発生した場合などに便利です。

3. MainへのPush時にデバッグビルドを実行

mainへのpushのたびにAndroidのdebug buildを生成することで、native buildのリグレッションを早期に検知します。 main実行コストが低く、フィードバックも速いので、純粋なスモークテストとしてPlay Storeへのアップロードをスキップできます。

name: Capgo Build (Main)

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'

jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android

      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

この paths filterにより、ドキュメントのみの変更ではworkflowが実行されないようにしています。 --no-playstore-upload Play Storeへの申請をスキップ（ PLAY_CONFIG_JSON 不要）し、 --output-upload 生成されたAPKのダウンロードURLを出力するので、テスト端末にインストールできます。

よくあるパターン

Play Store / TestFlight へのアップロードをスキップ

テストビルドでは、ストアへの提出をスキップできます。Android の場合は --no-playstore-upload; iOSの場合は、以下のコマンドでad-hocモードでビルドしてください --ios-distribution ad_hoc （App Storeには送信されません）。これらを組み合わせて使用することもできます。 --output-upload バイナリの期限付きダウンロードURLを取得するには

ストアリリースをレビューに提出する

デフォルトでは、リリースビルドは署名済みアーティファクトをアップロードし、最終的なストア操作はご自身で制御できます。ストアのレビューフローへ直接進めたいCIリリースでは、次を追加してください： --submit-to-store-review.

Androidでは、お使いの PLAY_CONFIG_JSON サービスアカウントを使用します。 トラックを明示しない場合、 --submit-to-store-review デフォルトでは、次の指定でproductionトラックになります： release_status: completed. 呼び出し側で次のようにトラックを明示することをお勧めします： --android-track (または PLAY_STORE_TRACK)、statusを上書きする場合は --android-release-status / PLAY_STORE_RELEASE_STATUS を必要に応じて指定します：

- name: Submit Android release for review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
    KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
    KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
    KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

本番環境ではなく、社内向けのリリースとして完了させる場合は以下の通りです：

- name: Submit Android internal release
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
    KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
    KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
    KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track internal \
      --store-release-name "${GITHUB_REF_NAME}"

iOSではApp Store ConnectのAPIキーパスを使用し、処理済みのTestFlightビルドをApp Storeの審査に提出します。これには app_store 配布権限が --ios-testflight-groups 外部ベータ配布は任意であり、App Storeの審査には必須ではありません：

- name: Submit iOS build to App Store review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
    APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
    APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
    APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
    APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

ビルド出力URLとQR code を読み取る

渡す --output-record <path> ビルド成功時にビルド成果物のURLとQR code をディスクに保存し、後続のステップで次を使用して読み取ります： build last-output。ログのスクレイピングや正規表現は不要です。

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json

- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json JSONレコード（以下を含む）を書き込み、 jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAtPNG形式のQR code を、 /tmp/build.json.qr.png. build last-output これを読み取ります：

--field outputUrl ダウンロードURLのみを出力します（改行付き。以下に URL=$(...)).
--field qrCodePngPath PNGのパスを出力します。これにより、PRの添付ファイルとしてアップロードできます。
--qr レンダリングされたASCII QRを出力します。PRのコメント内でMarkdownの code フェンス内に配置すれば、そのままスキャン可能です。

ビルド番号のインクリメントをスキップ

デフォルトでは、各リリースビルドでビルド番号が増加します。特定の値（Gitタグなど）に固定するには、以下を渡してください。 --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

依存関係のキャッシュ

bun install JS依存関係のキャッシュは効果が薄いことが多いですが、大規模プロジェクトでは Capacitor のネイティブ依存関係（CocoaPods、Gradle）をキャッシュする価値があります：

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

トラブルシューティング

症状	考えられる原因
`CAPGO_TOKEN is not set`	Secretが追加されていないか、ジョブにアクセス権がありません（環境/ブランチ保護を確認してください）
iOS / Androidの認証情報エラー	`gh secret set -f` 実行されていないか、別のリポジトリに対して実行されました。以下で確認してください `gh secret list`
`cap sync` ローカルでは動くがCIで失敗する	ネイティブプラグインが含まれていない `package.json`, または忘れている `bun install` の前に `cap sync`
ビルドは成功するがApp Store Connectにアプリが表示されない	チームIDが正しくないか、App Store Connectにアプリのレコードがまだ存在しません。ローカルで以下のコマンドを実行して確認してください： `bunx @capgo/cli@latest build credentials manage`
“Uploading project”の後にビルドが止まる	プロジェクトのアーカイブサイズが異常に大きいです — 以下を確認してください `node_modules` アップロードされていないか確認してください（デフォルトではアップロードされないはずです）
`Provisioning profile doesn't match bundle ID`	プロビジョニングマップが、Xcodeで署名されているものとは異なるbundle IDを指しています。再実行してください。 `build init` プロフィールを更新してから、次を使用して再エクスポートしてください： `build credentials manage`
ローカルの認証情報は更新したがCIで失敗し続ける	再エクスポートと再プッシュを忘れないでください： `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
マネージャーが結合ファイルの書き込みを拒否しました	プラットフォーム間で共有設定キーが異なります。マネージャーが警告し、確認を求めています。「上書き（一方が優先）」を確定するか、あるいは各プラットフォームごとに再エクスポートしてください： `--platform ios` / `--platform android`
`build last-output` 空のURLが出力されました	ビルドに失敗しました `--output-upload`、またはアーティファクトが生成される前に失敗しました。 `outputUrl` が実行されます `null` 記録内の、Branch on `[ -n "$URL" ]` を使用する前に
`build last-output` に関するエラー： `Unsupported record schemaVersion`	ランナーの CLI が、レコードを書き込んだものより古いバージョンです。両方のプロデューサーとリーダーを、同じ明示的なバージョン（例： `bunx @capgo/cli@7.104.0 …` の両方で）に固定してください。 `@latest`、これはフローティング状態でジョブ間で移動する可能性があります

プラットフォーム固有のビルド失敗については、以下を参照してください：トラブルシューティングガイド.

次のステップ

OTA / Native 自動切替 live update のアップロードと Capgo Build の間の Branch CI。

CI UI からトリガー Actions タブから、Capgo Build をオンデマンドで実行できます。

ビルド Webhook 管理ダッシュボードの HTTP コールから、同じワークフローを開始できます。

認証情報のセットアップ iOSおよびAndroidの認証情報をbase64シークレットとして準備するための完全リファレンス。

設定オプションビルドを微調整するための、すべてのCLIフラグと環境変数。