从 CI UI 触发 Native Build

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

有时你只需要一个已签名的 iOS 或 Android 二进制文件，而无需合并 PR 或创建 release tag —— 例如 QA 构建、应用商店重新提交或一次性的 TestFlight 测试。几乎所有主流的 code 托管平台都支持通过其 Web UI 启动流水线。本指南将介绍如何将该 UI 与 Capgo Build 连接起来。

你将获得

无需 Git 繁琐操作

点击 Run workflow / Run pipeline。Capgo Build 将根据你选择的分支进行编译。

安全的输入参数

在支持的托管平台（GitHub / Bitbucket / Azure）上，Platform 和 build mode 使用受限选项。除非你定义了 pipeline inputs，否则 GitLab 变量在每次运行时仍可编辑配合 options.

与 CI 使用相同的 Secrets

复用仓库中已有的 Capgo Build 凭据。无需在本地电脑进行额外配置。

前提条件

无论是在本地还是 CI 中，Capgo Build 均可正常工作 —— 请参阅快速入门
签名 Secrets 已存在于宿主环境中（用于 GitHub，通过 CLI 导出并 gh secret set -f)
CAPGO_TOKEN 以掩码 Secret 或 CI 变量形式存储

GitHub 操作

GitHub 的操作标签页可以启动任何声明了 workflow_dispatch.

1. 添加 workflow

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: Platform to build
        required: true
        default: both
        type: choice
        options: [ios, android, both]
      mode:
        description: Build mode
        required: true
        default: debug
        type: choice
        options: [debug, release]
      ref_note:
        description: Optional note for the run summary
        required: false
        type: string

jobs:
  build:
    runs-on: ubuntu-latest
    environment: ${{ inputs.mode == 'release' && 'production' || 'build-debug' }}
    strategy:
      fail-fast: false
      matrix:
        platform: ${{ fromJSON(inputs.platform == 'both' && '["ios","android"]' || format('["{0}"]', inputs.platform)) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: npm ci
      - run: npm run build
      - run: npx cap sync ${{ matrix.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 }}
        run: |
          EXTRA=""
          if [ "${{ inputs.mode }}" = "debug" ] && [ "${{ matrix.platform }}" = "android" ]; then
            EXTRA="--no-playstore-upload --output-upload"
          fi
          npx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode ${{ inputs.mode }} \
            $EXTRA

2. 从 UI 中运行

在浏览器中打开 GitHub 仓库
前往操作
选择 Capgo 构建 (手动)
点击 运行工作流
选择分支、平台和模式
确认 运行工作流

任何拥有写入权限的用户都可以启动构建。示例将 release 运行至名为 GitHub 的环境 production —— 请创建该环境并添加必要的审核人员，以便存储的构建等待审批。若没有 environment: 在任务中，环境保护规则将不会生效。

GitLab CI

GitLab 可以从以下位置运行任务： 构建 → Pipelines → 运行 pipeline 当该分支有可用任务时。

# Job fragment for .gitlab-ci.yml
stages:
  - build

variables:
  APP_ID: com.example.app
  PLATFORM: android   # override from Run pipeline UI
  BUILD_MODE: debug

capgo_native_manual:
  stage: build
  when: manual
  script:
    - npm ci
    - npm run build
    - npx cap sync "$PLATFORM"
    - |
      npx @capgo/cli@latest build request "$APP_ID" \
        --platform "$PLATFORM" \
        --build-mode "$BUILD_MODE"
  rules:
    # Actions / Pipelines UI → manual play button
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
    # Pipeline trigger token / webhook → run automatically
    - if: '$CI_PIPELINE_SOURCE == "trigger"'
      when: on_success
    - when: never

打开 GitLab 项目
前往 构建 → Pipelines → 运行 pipeline
选择分支
可选设置 PLATFORM / BUILD_MODE 本次运行的变量
启动 pipeline，然后点击 capgo_native_manual

when: manual 上的播放按钮；这可以防止每次 push 时都触发任务；通过 Web UI（或 pipeline 触发 Token）即可按需启动任务。

Bitbucket Pipelines

使用自定义 pipeline，以便 Bitbucket UI 能够传递变量：

pipelines:
  custom:
    capgo-native-build:
      - variables:
          - name: PLATFORM
            default: android
            allowed-values:
              - ios
              - android
          - name: BUILD_MODE
            default: debug
            allowed-values:
              - debug
              - release
      - step:
          name: Capgo Build
          image: node:24
          script:
            - npm ci
            - npm run build
            - npx cap sync "$PLATFORM"
            - npx @capgo/cli@latest build request com.example.app --platform "$PLATFORM" --build-mode "$BUILD_MODE"

运行方式： Pipelines → 运行 pipeline → Custom: capgo-native-build. 将 CAPGO_TOKEN 和签名材料存储在 仓库设置 → Pipelines → Repository variables.

Azure DevOps

trigger: none   # disable CI push triggers
pr: none        # also disable PR triggers (GitHub/Bitbucket-backed projects)

parameters:
  - name: platform
    displayName: Platform
    type: string
    default: android
    values:
      - ios
      - android
  - name: buildMode
    displayName: Build mode
    type: string
    default: debug
    values:
      - debug
      - release

pool:
  vmImage: ubuntu-latest

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '24.x'
  - script: |
      npm ci
      npm run build
      npx cap sync ${{ parameters.platform }}
      npx @capgo/cli@latest build request com.example.app \
        --platform ${{ parameters.platform }} \
        --build-mode ${{ parameters.buildMode }}
    env:
      CAPGO_TOKEN: $(CAPGO_TOKEN)
      # map other signing secrets from Library → Variable groups

trigger: none 以及 pr: none 让 pipeline 不参与自动 CI/PR 运行，这样它就从 流水线 → 运行流水线 （或 webhook）启动。如果项目使用 Azure Repos 分支策略将此 pipeline 加入队列，请单独禁用该策略。添加 CAPGO_TOKEN 并将签名值添加到标记为 secret 的变量组中。

输入	建议值	备注
平台	`ios`, `android`, `both`	矩阵运行时间 `both`
模式	`debug`, `release`	Debug + `--output-upload` 用于 QA 链接
iOS 分发	`app_store`, `ad_hoc`	Ad-hoc 永不提交至 App Store

安全说明

对于提交至商店的构建，建议优先使用环境保护规则 (GitHub) 或受保护变量 (GitLab) release 提交至商店的构建。
不要在 workflow 中写入签名密码 inputs — 请务必使用 secrets/variables。
通过仓库角色和团队权限限制 workflow 的运行权限（需拥有 GitHub 的 write 权限）。仅靠分支保护无法控制 运行 workflow；如果只有特定的小范围人员可以启动 build，请在 workflow 中添加授权检查。

GitHub Actions (完整配置) 导出凭据并推送/标记 workflow。

自动 OTA 或原生让 CI 在每次 push 时自动选择 live update 或 Capgo Build。

通过 Webhook 触发通过 HTTP 在管理后台调用相同的 pipeline。