立即免费开始

复制一个包含安装步骤和本插件的完整Markdown指南的设置命令。

Capgo 从笔记本电脑或 CI 任务开始构建。那些从 CI 任务中发布的团队 , CMS, 或内部门户通常希望一个单独的 HTTP webhook: 在他们自己的 UI 中点击一个按钮，一个带有签名的本机构建就会开始。这个指南展示了标准模式 —— 一种向您的 code 主机发送的带有认证的 HTTP 请求，这个请求会运行您已经使用的相同的 Capgo 构建工作流。

Architecture

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 来公开一个公共的“构建 webhook”。您的 CI 已经有了签名密钥； webhook 的唯一任务是安全地启动该 CI 任务。

前提条件

一个 Capgo 构建工作流程，已经可以从 CI UI 或推送（ CI UI 创建一个细粒度的 __CAPGO_KEEP_0__ token、GitLab 触发 token 或等效的权限GitHub 动作)
创建细粒度的GitHub令牌、GitLab触发令牌或等效令牌的权限
__CAPGO_KEEP_0__ Actions

选项 A — GitHub `repository_dispatch` (推荐)

GitHub 接受一个经过身份验证的 API 请求，启动一个监听 webhook 的工作流程 repository_dispatch.任何可以 POST JSON 可以触发它。

1. 监听 webhook 的工作流程

验证载荷在在checkout前，任何包含机密信息的步骤之前。将接受的值通过作业输出/环境变量传递 —— 不要进行插值。 client_payload 检出和在任何保密步骤之前。通过将接受的值传递到作业输出/环境变量 — 不要直接插值 run: scripts (脚本注入指南).

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

创建一个细粒度的个人访问令牌（或 GitHub App 安装令牌） 内容：读取和写入 在仓库上（用于 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 连接到您的管理 UI 中的按钮（“构建本机应用程序”）。仪表板只需到达您的后端; 后端持有 GITHUB_TOKEN.

选项 B — 小型代理 webhook (任何主机)

如果管理员工具只能将 POST 请求发送到您控制的 URL（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 到一个管理后台的常见形状是：后台存储一个 URL 和一个密钥；Capgo凭据在GitHub操作中。

GitLab Pipeline Trigger

GitLab 公开 pipeline触发器令牌复制到剪贴板

# .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"'

GitLab GitLab, 然后从管理后台:

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

对于两种平台，或者触发两次事件或者将任务扩展为并行矩阵，类似于 GitHub 示例。

Bitbucket 和 Azure

平台	Webhook 机制
Bitbucket	管道触发 URL 或自定义管道 + 应用密码 `POST`
Azure DevOps	Pipeline 运行 REST API 使用 PAT 进行 REST; 使用手动管道触发从 CI UI

模式相同：管理员 → 你的机密检查 → 主机 API → Capgo 构建作业

管理员工具的 Payload 检查清单

当仪表板表单构建时，收集至少：

平台 — iOS / Android / 双平台
模式 — debug (QA) 或 release (商店)
Git 分支 —— 构建分支或标签
Actor —— 用于审计日志的电子邮件或用户 ID（通过传递） client_payload)

Optional: 运行后，CI 将向管理员 API 发送下载 URL --output-record / build last-output.

安全性

验证每个 webhook（x-webhook-secret白名单
, 和 platform, mode在代理和工作流程中都 ref 作业 — 处理 validate 允许 client_payload 作为未经信任的输入。
将接受的值通过环境变量/作业输出传递;不要将载荷字段插入脚本。 run: scripts.
保持 GitHub/GitLab token在服务器端。
限制代理;原生构建耗费构建分钟。
对于提交到商店的版本，映射
到一个受保护的__CAPGO_KEEP_0__环境（如示例中所示）或要求额外的确认标志在 release 将其应用到受保护的GitHub环境（如示例中所示）或需要额外确认标志。 validate.

同一个__CAPGO_KEEP_0__构建作业，来自Actions/管道选项卡。同一 Capgo Build 任务，来自 Actions / Pipelines 选项卡的启动。

GitHub 操作设置这些工作流程使用的凭证导出和密钥名称

自动 OTA 或原生在 Git 推送时，自动选择 live update 或原生