GitHub 动作

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

您将获得

无人值守发布

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

无本地设置

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

范围内的密钥

您的凭据存储在 GitHub 仓库密钥中，仅对您的仓库和工作流程运行器可见。 rotate 和审计非常容易。

并行构建

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

前置条件

一个具有有效订阅和

• A Capgo account with an active subscription and a Capgo API key
• 您的应用程序已在 Capgo (如果没有)bunx @capgo/cli@latest app add 配置本地构建凭据
• —参见 bunx @capgo/cli@latest build init __CAPGO_KEEP_0__ 管理凭据 为向导教程
• 成功的本地构建（）— CI 不是调试第一个构建的地点bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug管理凭据
• __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ ( GitHub CLI (gh) 注意gh auth login)

以下流程假设您的本地凭据存储中已存在凭据（从

如果您还没有设置它们，请先这样做 — 向导会交互式地创建证书、配置文件、钥匙库和 Google Play 服务帐户 build init设置

设置

本地Capgo CLI可以将您的本地凭据导出为可直接使用的文件。结合此功能，整个CI/CD设置可以简化为三条命令——无需手动base64编码、无需JSON处理、无需逐一复制和粘贴。 .env 添加您的__CAPGO_KEEP_0__ __CAPGO_KEEP_1__密钥作为仓库密钥 gh secret set -f__CAPGO_KEEP_0__密钥不属于每个应用程序凭据存储，因此请手动添加一次：

1. Add your Capgo API key as a repository secret

   The API key isn’t part of the per-app credential store, so add it once manually:

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   上传 Capgo dashboard 此 功能 需要权限或更高的权限。

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

   运行交互式凭据管理器：

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

   在 TUI 中选择 导出到 .env. CLI 将 .env.capgo.<appId> 写入您的当前目录中，权限为 0600 (仅可读者) — 例如， .env.capgo.com.example.app. 当 iOS 和 Android 都配置时，两者的密钥将写入同一个文件中，位于 # === IOS === 和 # === ANDROID === section headers. iOS 和 Android env-var 名称是彼此独立的，所以组合它们是冲突的。

   需要一个每个平台的文件吗？

   通过 --platform ios (或 --platform android)来限定管理器到一个平台。然后导出会产生一个每个平台的文件，如 .env.capgo.com.example.app.ios。有用时 iOS 和 Android 秘密存储在不同的仓库或环境中。

   共享配置键

   一些配置开关（BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION)可以在每个平台独立存储并可能已经分离了。如果管理器发现分离，它会打印冲突的键，要求明确确认后写入，并将冲突列表作为文件顶部的注释嵌入。重新导出 --platform 如果您需要保留每个平台的值。

3. 将 .env 文件上传到GitHub Actions secrets

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

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

   That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.

   Push the

   file to GitHub Actions secrets

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

   texts":["终端窗口","复制到剪贴板","任何时候都可以重新导出凭证 — 文件不是一个长期存活的艺术品。",

4. 创建工作流文件","添加","到您的仓库中。选择以下三种触发模式之一，根据您希望如何触发构建。",

   最终会在您的密钥中出现","标题：最终会在您的密钥中出现" .github/workflows/capgo-build.yml ,

参考：","会创建以下仓库密钥（您的工作流 YAML 文件引用它们的确切名称）：","平台","创建的密钥"]

texts":["终端窗口","复制到剪贴板","任何时候都可以重新导出凭证 — 文件不是一个长期存活的艺术品。", gh secret set -f 创建工作流文件","添加","到您的仓库中。选择以下三种触发模式之一，根据您希望如何触发构建。",

最终会在您的密钥中出现","标题：最终会在您的密钥中出现"	,
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
(added manually)	CAPGO_TOKEN

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

工作流程示例

以下三个示例覆盖了最常见的模式。它们都使用相同的形状：查看仓库，安装依赖项，构建 Web 资产，同步到本机，然后调用 Capgo 使用环境变量传递凭据的 Build。

1. 手动触发

允许任何具有写入访问权限的人从 Actions 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.4.0变成你的发布命令。 git tag v1.4.0 && git push --tags /__CAPGO_KEEP_0__/工作流/__CAPGO_KEEP_1__-发布.yml

.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. 在主分支推送时进行调试构建

通过在每次推送到主分支时生成一个调试 Android 构建来尽早捕获本机构建回归。 main. cheap to run, fast feedback, and you can skip Google Play Store upload to keep it purely a smoke test.

.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

The paths filter ensures the workflow doesn’t run on doc-only changes. --no-playstore-upload skips Google Play Store submission (no PLAY_CONFIG_JSON needed), and --output-upload produces a download URL for the resulting APK so you can install it on a test device.

常见模式

跳过 Google Play Store / 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 服务帐户并将Google Play发布提交到Google Play Store，而不是将其留在未激活状态。添加 --store-release-name, --store-release-notes,以及可选 --store-release-notes-locale 条目，当您希望Play发布携带相同的标签和本地化的更改日志时：

- 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 \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

iOS 使用 App Store Connect API key path 并将处理好的 TestFlight 构建提交到 App Store 评审。它需要 app_store 分发; --ios-testflight-groups 对于外部 beta 分发而言是可选的，而对于 App Store 评审而言则不需要：

- 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

注意

此路径仅提交构建 artifact。App Store Connect 或 Google Play Console 中的商店列表元数据、测试者组、评审联系方式、合规答案和发布选择仍需要在 CI 运行前准备好。

读取构建输出 URL 和 QR code

通过 --output-record <path> 将构建 artifact 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（换行终止；安全用于 URL=$(...)).
• --field qrCodePngPath 打印 PNG 路径以便您可以将其作为 PR 附件上传。
• --qr 打印渲染的 ASCII QR — 将其放入 Markdown code 场所内 PR 评论中以便内联扫描。

注意

只有在构建成功时才会写入记录。未支持 schemaVersion 和未知 --field values exit non-zero, so a stale CLI in the runner fails loudly instead of silently emitting an empty URL.

跳过构建号增加

默认情况下，每个发布构建都会增加构建号。要将其固定到您控制的值（例如，Git标签），请传递 --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中失败，但本地正常	本地插件未在 package.json，或者你忘记了 bun install 之前 cap sync
构建成功，但在App Store Connect中没有应用出现在	团队ID错误，或者应用记录尚未在App Store Connect中存在。请本地验证 bunx @capgo/cli@latest build credentials manage
构建在“上传项目”后卡住	项目存档异常大——检查 node_modules 不被上传（它不应该默认上传）
Provisioning profile doesn't match bundle ID	Xcode 正在签署的 bundle ID 与配置文件指向的不同 - 重新运行 build init 重新刷新配置文件，然后重新导出 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或者在生成 artifact 之前就失败了。 outputUrl 将会 null 在记录中。 [ -n "$URL" ] 在
build last-output errors with Unsupported record schemaVersion	The runner is on an older CLI than the one that wrote the record。建议将生产者和读者都锁定在相同的明确版本（例如 bunx @capgo/cli@7.104.0 … on both sides）而不是 @latest，它会漂浮并在任务之间漂移

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

下一步

自动OTA或原生 Branch CI在实时更新上传和Capgo Build之间

从CI UI触发 从Actions选项卡手动运行Capgo Build.

构建 Webhooks 从管理员控制台 HTTP 请求中启动相同的工作流。

凭证设置 iOS 和 Android 凭证的 base64 秘密的全参考。

配置选项 所有 CLI 标志和环境变量以微调您的构建。