跳转到正文

从 CI UI 触发 Native Build

有时你需要一个已签名的 iOS 或 Android 二进制文件,但不想合并 PR 或打 release tag——比如 QA 构建、商店重新提交,或一次性的 TestFlight。所有主流 code 主机都可以通过其 Web UI 启动 pipeline。本指南将展示如何将此 UI 连接到 Capgo Build。

无需 Git 仪式

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

安全的输入

在主机支持的情况下(GitHub / Bitbucket / Azure),平台和构建模式使用受限选项。GitLab 变量在每次运行时保持可编辑,除非你定义了 流水线输入 配合 options.

与 CI 相同的 Secrets

复用仓库中已有的 Capgo Build 凭据。无需在本地配置新内容。

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

.github/workflows/capgo-build-manual.yml
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
  1. 在浏览器中打开 GitHub 仓库
  2. 前往 操作
  3. 选择 Capgo Build(手动)
  4. 点击 运行 workflow
  5. 选择分支、平台和模式
  6. 确认 运行 workflow

拥有 write 权限的人可以启动构建。示例将 release runs to a GitHub Environment named production — 创建该环境并添加必需的审核人员,以便商店构建在等待批准时暂停。如果没有 environment: 在任务中,环境保护规则始终不生效。

GitLab 可以从以下位置运行任务: 构建 → 流水线 → 运行流水线 当该分支的任务可用时。

# 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
  1. 打开 GitLab 项目
  2. 前往 构建 → 流水线 → 运行流水线
  3. 选择分支
  4. 可选地设置 PLATFORM / BUILD_MODE 本次运行的变量
  5. 启动 pipeline,然后点击 capgo_native_manual

when: manual 可防止每次 push 都触发任务;Web UI(或 流水线触发令牌)可按需启动。

使用自定义 pipeline,以便 Bitbucket UI 可以传递变量:

bitbucket-pipelines.yml
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 → Run pipeline → Custom: capgo-native-build. Store CAPGO_TOKEN 和签名材料位于 仓库设置 → Pipelines → 仓库变量.

azure-pipelines-capgo-manual.yml
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调试 + --output-upload 用于 QA 链接
iOS 分发app_store, ad_hocAd-hoc 不会提交到 App Store

如需可下载的 QA 产物,请将 Android debug 与 --no-playstore-upload --output-upload 并用以下方式读取 URL build last-output.

  • 优先使用环境保护规则 (GitHub) 或受保护变量 (GitLab),用于 release 提交至商店的构建。
  • 请勿在 workflow 中存放签名密码 inputs —— 仅存放在 secrets/variables 中。
  • 通过仓库角色和团队权限限制可运行 workflow 的人员(在 GitHub 上需要 write 权限)。仅靠分支保护无法控制 运行 workflow;如果只有更小的组才能启动构建,请添加 workflow 内的授权检查。