メインコンテンツにスキップ
Capgo - Capacitor アプリのリアルタイム更新 Capgo

ネイティブビルドをWebhookでトリガーする

Capgo ビルドは通常、ノートパソコンまたはCIジョブから開始されます。CIジョブからビルドするチームは管理画面からビルドする必要があります。 管理画面から、CMS、または内部ポータルは、単一の HTTP Webhook:自分のUIでボタンを押すと、署名されたネイティブビルドが開始される。 このガイドでは、標準パターンを示します — すでに使用しているCapgoビルドワークフローと同じcodeホストへの薄い認証済みHTTPコール。

構造

「構造」というタイトルのセクション

あなたは 必要ありません Capgo を公開する「ビルドWebhook」を公開する必要はありません。CIはすでに署名シークレットを持っています。Webhookの仕事は、CIジョブを安全に開始することだけです。

前提条件

「前提条件」というタイトルのセクション
  • Capgo ビルドワークフローがCI UIからすでに動作している場合、またはプッシュ ( __CAPGO_KEEP_0__ アクション CI UIGitHub Actions)
  • 細かい粒度のGitHubトークン、GitLabトリガー トークン、または同等のものの作成許可
  • 管理画面が送信する共有シークレット (ヘッダーまたはボディ)

オプション A — GitHub repository_dispatch （推奨）

「オプション A — GitHub リポジトリ ディスパッチ (推奨)」というセクション

GitHubは、有効なAPI呼び出しを受け取って、Webhookを待つワークフローを開始します。 repository_dispatchどのダッシュボードでも POST JSONでも送信できます。

1. Webhookを待つワークフロー

セクション「1. Webhookを待つワークフロー」

ペイロードを検証する 作業を始める前に、問題を提起して議論する チェックアウトと秘密情報を扱うステップの前に実行してください。 job の出力 / 環境変数を通じて受け入れた値を通過し、.interpolate を実行しない client_payload 直接 run: スクリプト (スクリプトのインジェクションに関するガイド).

github/workflows/capgo-build-webhook.yml
name: Capgo Build (Webhook)


on:
  repository_dispatch:
    types: [capgo-native-build]


jobs:
  validate:
    runs-on: ubuntu-latest
    outputs:
      platform: ${{ steps.check.outputs.platform }}
      mode: ${{ steps.check.outputs.mode }}
      ref: ${{ steps.check.outputs.ref }}
      platforms_json: ${{ steps.check.outputs.platforms_json }}
    steps:
      - id: check
        env:
          RAW_PLATFORM: ${{ github.event.client_payload.platform }}
          RAW_MODE: ${{ github.event.client_payload.mode }}
          RAW_REF: ${{ github.event.client_payload.ref }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
        run: |
          PLATFORM="${RAW_PLATFORM:-android}"
          MODE="${RAW_MODE:-release}"
          REF="${RAW_REF:-$DEFAULT_BRANCH}"
          case "$PLATFORM" in ios|android|both) ;; *)
            echo "Invalid platform: $PLATFORM" >&2; exit 1;;
          esac
          case "$MODE" in debug|release) ;; *)
            echo "Invalid mode: $MODE" >&2; exit 1;;
          esac
          # Allowlist branches / tags / full SHAs only
          if [[ ! "$REF" =~ ^(main|master|production|release/[A-Za-z0-9._-]+|[0-9a-f]{40})$ ]]; then
            echo "Ref not allowlisted: $REF" >&2
            exit 1
          fi
          if [ "$PLATFORM" = "both" ]; then
            PLATFORMS_JSON='["ios","android"]'
          else
            PLATFORMS_JSON=$(printf '["%s"]' "$PLATFORM")
          fi
          {
            echo "platform=$PLATFORM"
            echo "mode=$MODE"
            echo "ref=$REF"
            echo "platforms_json=$PLATFORMS_JSON"
          } >> "$GITHUB_OUTPUT"


  build:
    needs: validate
    runs-on: ubuntu-latest
    environment: ${{ needs.validate.outputs.mode == 'release' && 'production' || 'build-debug' }}
    strategy:
      fail-fast: false
      matrix:
        platform: ${{ fromJSON(needs.validate.outputs.platforms_json) }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.validate.outputs.ref }}


      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'


      - run: npm ci
      - run: npm run build
      - name: Sync native project
        env:
          PLATFORM: ${{ matrix.platform }}
        run: npx cap sync "$PLATFORM"


      - name: Capgo Build
        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 }}
          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 }}
          PLATFORM: ${{ matrix.platform }}
          MODE: ${{ needs.validate.outputs.mode }}
        run: |
          npx @capgo/cli@latest build request com.example.app \
            --platform "$PLATFORM" \
            --build-mode "$MODE"

2. GitHub トークンを作成する

セクションのタイトル：2. GitHub トークンを作成する

GitHub アプリのインストールトークン (または細かい粒度のパーソナル アクセス トークン) を作成します。 内容：読み書き リポジトリ上 ( __CAPGO_KEEP_0__ が必要) repository_dispatch。ブラウザに保存しないでください。

3. Webhookを管理画面から呼び出す

セクション「3. Webhookを管理画面から呼び出す」

あなたのバックエンド(ユーザー側のブラウザではありません)は次のことを行う必要があります:

ターミナル画面
curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{
    "event_type": "capgo-native-build",
    "client_payload": {
      "platform": "both",
      "mode": "release",
      "ref": "main",
      "requested_by": "admin@example.com"
    }
  }'
フィールド目的
event_type必ず一致する types ワークフロー内でcapgo-native-build)
client_payload.platformios, androidまたは both
client_payload.modedebug ブランチまたはタグをビルドする(任意) release
client_payload.refまたは

WireのJSON POSTを、管理画面のボタン（「ネイティブアプリをビルドする」）に接続します。ダッシュボードは「"} あなたの バックエンド; バックエンドは保持しています GITHUB_TOKEN.

オプション B — どのホストでも動作する小型プロキシ Webhook

「オプション B — 任何ホストの小さなプロキシ Webhook」

もし管理者ツールがURLを制御できるPOSTのみに制限されている場合（Zapier、Make、Cloudflareワーカー、Expressルート）、GitHubの短いプロキシを置きます。

// Example Cloudflare Worker / Node handler (sketch)
export default {
  async fetch(request, env) {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 })
    }
    if (request.headers.get('x-webhook-secret') !== env.WEBHOOK_SECRET) {
      return new Response('Unauthorized', { status: 401 })
    }
    const body = await request.json().catch(() => ({}))
    const platform = body.platform || 'both'
    const mode = body.mode || 'release'
    const ref = body.ref || 'main'
    if (!['ios', 'android', 'both'].includes(platform)) {
      return new Response('Invalid platform', { status: 400 })
    }
    if (!['debug', 'release'].includes(mode)) {
      return new Response('Invalid mode', { status: 400 })
    }
    if (!/^(main|master|production|release\/[A-Za-z0-9._-]+|[0-9a-f]{40})$/.test(ref)) {
      return new Response('Ref not allowlisted', { status: 400 })
    }
    const res = await fetch(
      `https://api.github.com/repos/${env.GITHUB_OWNER}/${env.GITHUB_REPO}/dispatches`,
      {
        method: 'POST',
        headers: {
          Accept: 'application/vnd.github+json',
          Authorization: `Bearer ${env.GITHUB_TOKEN}`,
          'X-GitHub-Api-Version': '2022-11-28',
        },
        body: JSON.stringify({
          event_type: 'capgo-native-build',
          client_payload: { platform, mode, ref },
        }),
      },
    )
    return new Response(res.status === 204 ? 'Build queued' : await res.text(), {
      status: res.status === 204 ? 200 : res.status,
    })
  },
}

次に、管理製品を設定してください。

設定値
URLhttps://your-worker.example.com/native-build
メソッドPOST
ヘッダーx-webhook-secret: <shared secret>
本文{ "platform": "both", "mode": "release" }

通常のWebhook接続の形状は、管理者用ダッシュボードに接続する場合です: ダッシュボードは1つのURLと1つのシークレットを保存し、Capgoの資格情報はGitHubのアクションに残ります。

GitLab Pipeline トリガー

「GitLab Pipeline トリガー」のセクション

GitLabは pipelineトリガー用のトークン 自然なWebhookのターゲットです。

# .gitlab-ci.yml fragment
capgo_native_webhook:
  stage: build
  script:
    - npm ci && npm run build
    - npx cap sync "${PLATFORM:-android}"
    - npx @capgo/cli@latest build request com.example.app --platform "${PLATFORM:-android}" --build-mode "${BUILD_MODE:-release}"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "trigger"'

トリガー用トークンを作成する 設定 → CI/CD → パイプライントリガー用トークン, から管理画面の:

ターミナル画面
curl -X POST \
  -F token=$GITLAB_TRIGGER_TOKEN \
  -F ref=main \
  -F "variables[PLATFORM]=android" \
  -F "variables[BUILD_MODE]=release" \
  https://gitlab.com/api/v4/projects/PROJECT_ID/trigger/pipeline

両方のプラットフォームでは、2つのトリガーを発火するか、ジョブを平行マトリックスに展開する方法は、GitHub の例と同じようにします。

Bitbucket と Azure

「Bitbucket と Azure」セクション
プラットフォームWebhook メカニズム
Bitbucketパイプライントリガー URL またはカスタムパイプライン + アプリパスワード POST
Azure DevOpsパイプライン実行REST API パーソナルアクセストークン(PAT)を使用し、手動パイプラインを使用します。 CI UIからトリガー

パターンは同じです：管理者 → 秘密のチェック → ホスト API → Capgo ビルドジョブ。

管理ツール用ペイロードチェックリスト

セクションのタイトル “管理ツール用ペイロードチェックリスト”

ダッシュボードフォームが作成されたときに、少なくとも次の情報を収集する必要があります。

  • プラットフォーム —— ios / android / 両方
  • モード — debug (QA) or release (store)
  • Git ref — branch or tag to build
  • Actor — メールアドレスまたはユーザID（監査ログの通過） client_payload)

Optional: after the run, have CI post back to the admin API with the download URL from --output-record / build last-output.

セキュリティ

セキュリティ
  • すべてのウェブホークを認証する (x-webhook-secret許可リスト
  • 、および platform, mode, and ref プロキシとワークフロー両方で validate ジョブ — 取り扱い client_payload 信頼できない入力として
  • 受け入れられた値を環境変数/ジョブ出力として通過し、ペイロードフィールドをスクリプトに埋め込まない。 run: スクリプト。
  • GitHub/GitLab トークンはサーバー側のみに保管する。
  • リポジトリ単位のトークンを優先する。
  • プロキシを制限する;ネイティブビルドはビルド分数に費やされる。
  • ストアに提出するリリースの場合、サンプルに示すように保護された__CAPGO_KEEP_0__環境にマップするか、追加の確認フラグをチェックする必要がある。 release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.
関連ガイド
CI UI からトリガーする 同じCapgoビルドジョブ、Actions / Pipelines タブから開始します。
GitHub Actions の設定 これらのワークフローで使用される資格情報のエクスポートとシークレット名
Auto OTA またはネイティブ git push のときにライブアップデートとネイティブを自動的に選択します。