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

コピー可能なセットアップ用の質問

Capgo ビルドは通常、ノートパソコンまたはCIジョブから開始されます。シップするチームは、 管理画面HTTP Webhook 注: press a button in their own UI, and a signed native build starts. This guide shows the standard pattern — a thin authenticated HTTP call into your code host, which runs the same Capgo Build workflow you already use.

あなたは

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

あなたは行います not need Capgo to expose a public “build webhook.” Your CI already has the signing secrets; the webhook’s only job is to start that CI job safely.

前提条件

既存のCapgoビルドワークフローがCI UIからもしくはプッシュ( CI UI __CAPGO_KEEP_0__トークン、GitLabトリガー用トークン、または同等の権限GitHub アクション)
オプションA — GitHub
(推奨)

「オプションA — GitHub repository_dispatch (推奨)」 `repository_dispatch` (recommended)

GitHub は、有効な API を受け取ってワークフローを開始し、 repository_dispatch. どのダッシュボードでも POST JSON で送信できる

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

ペイロードを検証する前にチェックアウトし、秘密情報を扱うステップの前に。 job の出力 / 環境変数を通じて受け入れた値を渡す — script に直接入力しない 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 アプリのインストールトークン（または細かい粒度のパーソナルアクセストークン）を作成します。 内容：読み書き リポジトリ上（__CAPGO_KEEP_0__ トークンが必要） 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`	ブランチまたはタグをビルドする (任意)

同じ JSON POST をボタンにワイヤーする。管理画面のダッシュボードは、 あなたの バックエンドに到達するだけで済みます; バックエンドは GITHUB_TOKEN.

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

Cloudflare の管理ツールは、URL を制御する場所に POST することができます (Zapier、Make、Cloudflare Worker、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,
    })
  },
}

次に、管理製品を設定します:

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

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

GitLabパイプライントリガー

GitLabはパイプライントリガータークンが自然な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"'

Settings → CI/CD → Pipeline trigger tokens で、管理画面からターミナル画面

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	パイプライントリガー URL またはカスタムパイプライン + アプリパスワード `POST`
Azure DevOps	パイプライン実行 REST API PAT を使用して、手動パイプラインから CI UI からトリガー

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

Payload Checklist for Admin Tools

Dashboardフォームが作成されたときに、少なくとも以下の情報を収集する必要があります。

プラットフォーム — ios / android / どちらか
モード — debug (QA) または release (store)
Git ref — branch または tag をビルドする
アクター — アクセスログのためにemailまたはuser idを通過する client_payload)

オプション:実行後、CIはadmin APIにダウンロードURLを送信する --output-record / build last-output.

セキュリティ

すべてのウェブホックを認証する (x-webhook-secretホワイトリスト
、および platform, mode, and ref ジョブ — これらの値を validate 信頼できない入力として扱う。 client_payload 受け入れた値を環境変数/ジョブ出力経由で通過する; プレースホルダーをウェブホックのペイロードフィールドに埋め込まない。
__CAPGO_KEEP_0__/GitLab トークンはサーバー側のみに保管すること。 run: セキュリティ
Keep GitHub/GitLab tokens server-side only.
リポジトリ単位のトークンを優先します。
プロキシの制限率を設定し、ネイティブビルドのコストはビルド分数になります。
For store-submitting releases, map release ストアにリリースする場合、GitHub 環境にマップします。 validate.

セクション「関連ガイド」同一 Capgo ビルドジョブ、Actions / Pipelines タブから開始されました。

同じ GitHub ビルドジョブ、Actions / Pipelines タブから開始します。 __CAPGO_KEEP_0__ Actions 設定

context: Capgo ソリューションズマーケティングページ。役割: 短い UI ラベルまたはナビゲーションアイテム。ページ: solutions/build-without-mac.astro。Capgo製品/ブランドと開発者用語を完全に保存します。メッセージキー `solutions_build_without_mac_link_github_actions` (ソリューションズビルドウィズアウトマックリンクGithubアクション)。 git push のときは、live update とネイティブの自動選択を選びます。