GitHub Actions

从您的 GitHub 仓库直接自动化 iOS 和 Android 构建。使用一个工作流文件和少量仓库密钥，任何推送、标签或手动触发都可以生成签名、商店准备好的应用程序——无需团队成员安装 Mac、Xcode 或 Android Studio。

您将获得

在 Git 中标记一个发布，您的签名 iOS 和 Android 二进制文件将自动提交到 TestFlight 和 Play Store。

无本地设置

无需在本地设置任何东西

Windows 或 Linux 的贡献者可以触发 iOS 构建。无需 Xcode、无需配置、无需在笔记本电脑上共享签名证书。

Scoped Secrets

凭据存储在 GitHub 仓库中的机密中，仅对工作流程运行器可见，且仅限于您的仓库。易于轮换，易于审计。

并行构建

构建 iOS 和 Android 同时使用矩阵作业。典型的发布在 10 分钟内完成。

前提条件

一个 __CAPGO_KEEP_0__ 帐户，具有活跃的订阅和一个 __CAPGO_KEEP_1__ 密钥

• 您的应用程序在 Capgo 中注册（如果尚未注册） Capgo API key
• Your app registered in Capgo (bunx @capgo/cli@latest app add 一个 __CAPGO_KEEP_0__ 帐户，具有活跃的订阅和一个 __CAPGO_KEEP_1__ 密钥
• 本地配置的构建凭证 bunx @capgo/cli@latest build init — 见 管理凭证 为向导教程
• 成功的本地构建（bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug）— CI 不是调试第一次构建的地点
• The GitHub CLI (gh) 已安装并已验证（gh auth login)

注意

以下流程假设您的本地凭证存储中已存在凭证（从 build init. 如果您尚未设置，请先进行设置 — 该向导会交互式地创建证书、配置文件、钥匙串和 Play Store 服务帐户。

设置

The Capgo CLI can export your local credentials as a ready-to-use .env 文件。 gh secret set -f结合

1. 添加您的 Capgo API 密钥作为一个仓库密钥

   API 密钥不属于每个应用程序的凭证存储，因此请手动添加一次：

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   在 __CAPGO_KEEP_0__ 控制台中生成密钥 Capgo dashboard 与 上传 具有权限或更高的权限。

2. 将您的凭据导出到一个 .env 文件

   在交互式凭据管理器中运行:

   bunx @capgo/cli@latest build credentials manage --appId com.example.app

   在 TUI 中选择 导出到 .env. CLI 将 .env.capgo.<appId> 以模式 0600 (仅 owner 可读) — 例如 .env.capgo.com.example.app. 当 iOS 和 Android 都配置时，两个平台的密钥会出现在同一个文件下 # === IOS === 和 # === ANDROID === 区域

   需要每个平台的文件吗

   需要每个平台的文件吗 --platform ios 通过 --platform android(或 .env.capgo.com.example.app.ios) 来限定管理器到一个平台。然后导出会产生一个每个平台的文件，如

   共享配置键

   A handful of config toggles (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION)可以在每个平台下独立存储，并且可能会分开。 如果管理器发现分离，它会打印冲突的键，要求明确确认写入，并将冲突列表作为文件顶部的注释。重新导出以 --platform if需要保留每个平台的值。

3. Push文件到__CAPGO_KEEP_0__ Actions secrets .env file to GitHub Actions secrets

   命令读取一个dotenv文件并为每行创建一个存储库密钥： gh secret set -f 终端窗口 KEY=value 复制到剪贴板

   gh secret set -f .env.capgo.com.example.app

   file to GitHub Actions secrets gh secret list.

   Don't commit the .env file

   It contains plaintext signing material. Once you’ve pushed it to GitHub:

   echo '.env.capgo.*' >> .gitignore
   rm .env.capgo.*

   任何时候都可以重新导出凭证 — 文件不是一个长期存活的艺术品。

4. 创建工作流文件

   添加 .github/workflows/capgo-build.yml 到您的仓库中。根据您希望触发构建的方式，选择以下三个触发模式之一。

最终会出现在您的密钥部分中的内容

参考 gh secret set -f 会创建这些仓库密钥（您的工作流 YAML 文件通过这些确切名称引用它们）：

平台	创建的机密
iOS	BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
Android	ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON
(手动添加)	CAPGO_TOKEN

您不需要记住这些 — 下面的工作流程示例已经引用了所有它们。

工作流程示例

以下三个示例覆盖了最常见的模式。它们都使用相同的形状：检查出仓库，安装依赖项，构建 Web 资产，同步到原生，然后调用 Capgo Build with credentials passed as environment variables。

1. 手动触发

允许任何具有写入访问权限的人从触发一个构建 动作 在 GitHub 中的标签页，包含一个平台下拉菜单。对于 ad-hoc 测试构建或按需触发发布非常有用。

.github/工作流程/capgo-手动构建.yml

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync

      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          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: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

替换 com.example.app 用你的应用 ID 替换。 一旦提交，前往 动作 → Capgo 构建（手动） → 运行工作流 触发它。

2. 根据标签发布

在推送一个版本标签（如 v1.0）时，会并行构建和发布两个平台。这是最常见的生产环境设置 — v1.4.02. 根据标签发布 git tag v1.4.0 && git push --tags 变成您的发布命令。

github/workflows/capgo-build-release.yml

name: Capgo Build (Release)

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}

      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          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
          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: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

矩阵在 iOS 和 Android 上分别在单独的运行器上并行运行。设置 fail-fast: false 意味着一个 iOS 构建失败不会取消正在进行的 Android 构建（反之亦然）—当一个平台出现暂时性签名问题时很有用。

注意

关于版本号： Capgo 构建自动增加您的构建号于每次发布构建。如果您愿意将其固定到标签，请参见 跳过构建号增加 以下

3. Debug 在推送到主分支

通过在每次推送到生成一个调试安卓构建来捕捉本地构建回归问题， main成本低，反馈快，可以跳过在Play Store上发布以保持它纯粹的烟雾测试

github/workflows/capgo-build-main.yml

name: Capgo Build (Main)

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'

jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android

      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          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 }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

该 paths 过滤器确保工作流程不会在仅文档更改时运行。 --no-playstore-upload 跳过Play Store提交（无 PLAY_CONFIG_JSON 需要），并 --output-upload 生成下载APK的URL以便在测试设备上安装它。

常见模式

跳过 Google Play 商店 / TestFlight 上传

对于测试构建，跳过商店提交：Android 使用 --no-playstore-upload;对于 iOS，使用 --ios-distribution ad_hoc (它永远不会提交到 App Store).将其与 --output-upload 来获取对二进制文件的有限期下载 URL。

提交商店发布进行审查

默认情况下，发布构建上传签名的 artifact 并将最终商店操作留给您控制。对于 CI 发布，应直接进入商店审查流程，请添加 --submit-to-store-review.

Android 使用您的 PLAY_CONFIG_JSON 服务帐户。 没有明确的跟踪时， --submit-to-store-review defaults to the production track with release_status: completed. Prefer stating the track at the call site with --android-track ( PLAY_STORE_TRACK) --android-release-status / PLAY_STORE_RELEASE_STATUS , and override status with

- name: Submit Android release for review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    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: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

Copy to clipboard

- name: Submit Android internal release
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    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: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track internal \
      --store-release-name "${GITHUB_REF_NAME}"

iOS uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store iOS使用App Store Connect__CAPGO_KEEP_0__key path并将处理的TestFlight build提交到App Store review。它需要 --ios-testflight-groups distribution;

- name: Submit iOS build to App Store review
  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 }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

注意

仅提交构建产物的路径。请在 App Store Connect 或 Google Play Console 中准备应用商店列表元数据、测试组、审阅联系人信息、合规答案和发布选项，CI 运行前这些信息仍需要准备好。

读取构建输出 URL 和 QR code

通过 --output-record <path> 为了在构建成功时将构建产物 URL 和 QR code 持久化到磁盘，然后在随后的步骤中使用 build last-output。无需日志爬取、无需正则表达式。

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json

- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json 将 JSON 记录（带有 jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt)和一个 PNG QR code放在 /tmp/build.json.qr.png. build last-output 读取它：

• --field outputUrl 打印仅下载 URL（换行终止；安全用于”，“打印 PNG 路径以便将其作为 PR 附件上传。”，“打印渲染的 ASCII QR — 将其放入 PR 评论中的 Markdown __CAPGO_KEEP_0__ 场所以便实现内联扫描。”，“注意”,”注意”,”只有在构建成功时才会写入记录。未支持的”,”和未知的”,”值会退出非零，因此在 runner 中出现过时的 __CAPGO_KEEP_0__ 会大声失败而不是静默地发出一个空的 URL。”,”跳过构建号码增加”,”标题：跳过构建号码增加”,”默认情况下，每个发布构建都会增加构建号码。要将其固定到您控制的值（例如 Git 标签），请传递”,”复制到剪贴板”]}] } URL=$(...)).
• --field qrCodePngPath targetLanguage
• --qr prints the rendered ASCII QR — drop it inside a Markdown code fence on the PR comment for inline scannability.

items

text schemaVersion Note --field values exit non-zero, so a stale CLI in the runner fails loudly instead of silently emitting an empty URL.

Section titled “Skip build number bumping”

By default each release build increments the build number. To pin it to a value you control (for example, the Git tag), pass --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

缓存依赖项

bun install 通常，JS依赖项缓存并不会带来太大的性能提升，但 Capacitor 的原生依赖项（CocoaPods，Gradle）在大型项目中值得缓存：

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

故障排除

症状	可能原因
CAPGO_TOKEN is not set	未添加密钥或作业无权访问（检查环境/branch保护）
缺少 iOS / Android 凭证错误	gh secret set -f 未运行或运行的是不同仓库。请使用 gh secret list
cap sync CI 中失败但本地成功	A native plugin 不存在 package.json或您忘记了 bun install 在 cap sync
创建一个问题并在工作于新功能之前讨论	在 bunx @capgo/cli@latest build credentials manage
构建成功但应用程序在 App Store Connect 中未显示	错误的团队 ID 或应用程序记录尚未在 App Store Connect 中存在。请使用 node_modules 构建在“上传项目”之后卡住
Provisioning profile doesn't match bundle ID	项目存档过大 — 检查是否正在上传（它不应默认上传) build init 配置文件指向的 bundle ID 与 Xcode 签名的 ID 不同。重新运行 build credentials manage
以刷新配置文件，然后重新导出	本地更改了凭据，但 CI 还是失败了 bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
经理拒绝写入组合文件	共享配置键在不同平台之间有所不同 — 经理会警告并要求确认。要覆盖其中一个，或者重新导出每个平台的配置 --platform ios / --platform android
build last-output 打印一个空的URL	构建未通过 --output-upload或者在生成工件之前失败 outputUrl 将 null 在记录中 [ -n "$URL" ] 在
build last-output 使用它之前 Unsupported record schemaVersion	The runner is on an older CLI than the one that wrote the record. Pin both producer and reader to the same explicit version (e.g. bunx @capgo/cli@7.104.0 … 错误 @latest运行器位于一个旧的__CAPGO_KEEP_0__版本上，而记录的生成者使用的是一个更新的版本。请将生成者和读者都固定在相同的显式版本上（例如

对于平台特定的构建失败，请参阅 故障排除指南.

下一步

自动OTA或本机 分支CI在实时更新上传和Capgo构建之间

从CI UI触发 从Actions选项卡按需运行Capgo构建

构建Webhook 从管理员控制台HTTP调用启动相同的工作流

凭证设置 iOS和Android凭证准备的base64密钥的完整参考

配置选项 所有 CLI flags 和环境变量，用于微调您的构建。