Webhook経由でNative Buildをトリガー

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

Capgo Buildは通常、ラップトップまたはCIジョブから開始されます。デプロイするチームは 管理ダッシュボード、CMS、社内ポータルなどから単一の HTTP webhookをよく求めます。自社UIのボタンを押すと、署名済みのNative Buildが開始されます。本ガイドでは標準パターンを紹介します — 認証済みの軽量なHTTPコールをお使いのcodeホストに送り、既存のCapgo Buildワークフローをそのまま実行します。

アーキテクチャ

sequenceDiagram
  participant Admin as Admin dashboard
  participant Hook as Webhook endpoint
  participant CI as GitHub / GitLab
  participant Capgo as Capgo Build

  Admin->>Hook: POST /native-build (secret)
  Hook->>CI: repository_dispatch / pipeline trigger
  CI->>CI: checkout, npm ci, cap sync
  CI->>Capgo: build request
  Capgo-->>CI: signed binary / store upload

次の場合には 決して 公開用の「build webhook」を公開するには Capgo が必要です。署名用のシークレットは既にCI側で管理されているため、webhookの役割は、そのCIジョブを安全に開始することだけです。

前提条件

すでに動作している Capgo Buildワークフローを、 CI UI または push 時に（GitHub アクション)
fine-grained な GitHub トークン、GitLab トリガートークン、または同等のものを作成する権限
管理ダッシュボードから送信される共有シークレット（ヘッダーまたはボディ）

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

GitHub は認証済みの API 呼び出しを受け取り、次のイベントを待ち受けるワークフローを開始します repository_dispatch. JSONを送信できるあらゆるダッシュボードから POST Webhookをトリガーできます。

1. Webhookをリッスンするワークフロー

ペイロードの検証 の前に checkout後、および機密情報を扱うステップの前に必ず行ってください。承認された値はjobのoutputsや環境変数経由で渡してください。直接 client_payload 以下に run: スクリプト (スクリプトインジェクションに関するガイダンス).

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 トークンを作成

以下の方法で、権限を絞ったパーソナルアクセストークン（または GitHub App インストール用トークン）を作成します。 内容: Read and write on the repository (required for repository_dispatch作成したトークンは管理用バックエンドにのみ保存してください。ブラウザには絶対に保存しないでください。

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.platform`	`ios`, `android`、または `both`
`client_payload.mode`	`debug` または `release`
`client_payload.ref`	ビルド対象のブランチまたはタグ (任意)

管理UIのボタン（「Build native apps」など）に、同じJSON POSTを紐付けます。ダッシュボードは あなたの バックエンドに接続するだけで済みます。バックエンドが GITHUB_TOKEN.

オプション B — 小さなプロキシ Webhook（任意のホスト）

管理ツールが、自分で管理する URL（Zapier、Make、Cloudflare Worker、Express ルート）にしか POST できない場合は、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,
    })
  },
}

次に、管理ツールを設定します：

設定	値
URL	`https://your-worker.example.com/native-build`
メソッド	`POST`
ヘッダー	`x-webhook-secret: <shared secret>`
ボディ	`{ "platform": "both", "mode": "release" }`

これは、Webhook を管理者向けダッシュボードに接続するときのよくある構成です。ダッシュボードには URL とシークレットを 1 つずつ保存し、Capgo の認証情報は GitHub Actions に保持します。

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 → Pipelineトリガー用トークン、次に管理画面から以下を行います：

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

プラットフォーム	Webhook の仕組み
Bitbucket	Pipeline トリガー URL またはカスタム Pipeline + App Password `POST`
Azure DevOps	PAT を使用した Pipeline 実行 API 手動 Pipeline を使用してください CI UI からトリガー

パターンは同一：admin → シークレット確認 → API ホスト → Capgo Build ジョブ

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

ダッシュボードのフォーム作成時には、少なくとも以下を収集してください：

プラットフォーム — iOS / Android / 両方
モード — debug (QA) または release（ストア）
Git ref — ビルド対象の branch または tag
実行者 — 監査ログ用のメールアドレスまたはユーザーID（そのまま渡す） client_payload)

任意：実行後、CIから admin API へ、ダウンロードURLを添えてポストバックします --output-record / build last-output.

セキュリティ

すべてのWebhookを認証してください（x-webhook-secretHMAC署名、またはmTLS）。
Allowlistを platform, modeや ref プロキシとワークフローの両方で行い、 validate ジョブ内では、 client_payload 信頼できない入力として扱ってください。
受け付けた値は環境変数やジョブの出力経由で渡してください。ペイロードのフィールドを run: scripts.
GitHub/GitLabのトークンは、必ずサーバー側のみで管理してください。
単一のリポジトリにスコープされたトークンの使用を推奨します。
プロキシにレート制限を設けてください。Native Buildにはビルド時間（build minutes）が消費されます。
ストア申請用のリリースについては、 release 保護された GitHub 環境にマッピングするか（サンプル参照）、または追加の確認フラグを必須にします。 validate.

CI UI からトリガー Actions / Pipelinesタブから開始される、同じ Capgo Buildジョブ内でチェックします。

GitHub Actions のセットアップこれらのワークフローで使用される認証情報のエクスポート名とシークレット名。

OTA / Native 自動切替 git push時に、live update か native かを自動的に選択します。