通过 Webhook 触发 Native Build

Capgo Build 通常从笔记本电脑或 CI 任务启动。那些通过 管理后台、CMS 或内部门户发布的团队，通常希望只需一个 HTTP webhook：在自己的 UI 中点击按钮，就能启动经过签名的 Native Build。本指南介绍标准模式——向你的 code 主机发起一个轻量的已认证 HTTP 调用，由它运行你已在使用的同一套 Capgo Build 工作流。

注意

Capgo 组织 Webhooks (Dashboard → Organization → Webhooks) 会通知 你的 有关 Capgo 事件 (bundles, channels, members) 的 URL。本页介绍反向流程： 你的 系统调用 URL 以 启动 触发 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

需要 不会 需要 Capgo 暴露一个公开的 “build webhook”。您的 CI 已拥有签名密钥；webhook 的唯一职责是安全地启动该 CI 任务。

前提条件

• 一个已在以下环境运行的 Capgo Build 工作流： CI UI 或通过 push (GitHub 操作)
• 创建细粒度 GitHub token、GitLab trigger token 或同等权限
• 您的 admin dashboard 将发送的共享密钥 (header 或 body)

方案 A — GitHub repository_dispatch (推荐)

GitHub 接受经过身份验证的 API 调用，从而启动监听... repository_dispatch. 任何支持 POST JSON 的 dashboard 都可以触发它。

1. 监听 Webhook 的工作流

验证 Payload 在……之前 在 checkout 之后以及任何涉及 secret 的步骤之前进行验证。通过 job outputs 或 env vars 传递已验证的值 —— 切勿直接插值到 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 token

创建细粒度的个人访问 token（或 GitHub App 安装 token），权限如下： 内容：读取和写入 on the repository (required for repository_dispatch）。请仅将其保存在管理后台，切勿放在浏览器中。

3. 从管理 dashboard 调用 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 请求绑定到管理 UI 的按钮上（“Build native apps”）。Dashboard 仅需访问 你的 后端；后端负责持有 GITHUB_TOKEN.

注意

切勿在前端 JavaScript 中嵌入 GitHub token。管理页面应调用您的服务器，由您的服务器调用 GitHub。

方案 B — 轻量级代理 Webhook（任意主机）

如果管理工具只能向你控制的 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
Header	x-webhook-secret: <shared secret>
Body	{ "platform": "both", "mode": "release" }

这是将 Webhook 连接到管理后台的常见方式：后台存储一个 URL 和一个 secret；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"'

在以下路径创建 trigger token： 设置 → 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

对于两个平台，可以触发两次 trigger，或者像 GitHub 示例那样，将 job 扩展为并行矩阵。

Bitbucket 与 Azure

平台	Webhook 机制
Bitbucket	Pipeline 触发 URL 或自定义 pipeline + app password POST
Azure DevOps	使用 PAT 调用 Pipeline run REST API ；使用来自 从 CI UI 触发

模式一致：admin → 您的密钥校验 → 托管 API → Capgo Build 任务。

管理工具 Payload 检查清单

构建 dashboard 表单时，请至少收集以下信息：

• 平台 — iOS / Android / 两者皆是
• Mode — debug (QA) 或 release (store)
• Git ref — 用于构建的 branch 或 tag
• Actor — 用于审计日志的 email 或 user id (透传) client_payload)

可选：运行结束后，让 CI 将下载 URL 回传给管理端 API --output-record / build last-output.

安全

• 验证每个 webhook (x-webhook-secret，HMAC 签名或 mTLS)。
• 设置白名单 platform, mode，以及 ref 在代理和 workflow validate job 中均需设置 — 将 client_payload 视为不可信输入。
• 通过环境变量/job outputs 传递已验证的值；切勿将 payload 字段插值到 run: scripts 中。
• 仅在服务端保留 GitHub/GitLab tokens。
• 优先使用仅限单个仓库作用域的 token。
• 对代理进行速率限制；Native Build 会消耗构建时长。
• 对于提交至应用商店的版本，请将 release 映射到受保护的 GitHub 环境（如示例所示），或要求在 validate.

相关指南

从 CI UI 触发 相同的 Capgo 构建任务，从 Actions / Pipelines 标签页启动。

GitHub Actions 设置 这些工作流使用的凭据导出和 Secret 名称。

自动 OTA 或原生 在 git push 时，自动选择 live update 或 Native。