GitHub 动作

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

您将获得

无人值守发布

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

无本地设置

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

范围内密钥

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

并行构建

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

前置条件

一个具有有效订阅和 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 密钥的 __CAPGO_KEEP_0__ 帐户

• 您的应用程序已在 Capgo (如果没有，请 Capgo API key
• Your app registered in Capgo (bunx @capgo/cli@latest app add —
• see bunx @capgo/cli@latest build init — 管理凭据 为向导教程
• 成功的本地构建（bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug") — CI 不是调试第一次构建的地方
• 管理 GitHub CLI (gh) 已安装并已验证（gh auth login)

注意

以下流程假设您的本地凭据存储中已存在凭据（从 build init")。如果您尚未设置它们，请先做好准备 — 向导会交互式地创建证书、配置文件、密钥库和 Google Play 服务帐户。

设置

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 __CAPGO_KEEP_1__ 可以将您的本地凭据导出为可直接使用的文件。结合此功能，整个CI/CD设置就可以通过三个命令完成 — 无需手动进行base64编码、无需处理JSON、无需逐一复制粘贴密钥。 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ key __CAPGO_KEEP_0__ permissions or higher.

2. Export your credentials to a .env file

   Run the interactive credentials manager:

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

   In the TUI, select Export to .env. The CLI writes .env.capgo.<appId> to your current directory with mode 0600 (owner-readable only) — for example, .env.capgo.com.example.app. When both iOS and Android are configured, both platforms’ secrets land in the same file under # === IOS === 和 # === ANDROID === iOS 和 Android 环境变量名是互不相容的，所以组合它们是冲突的。

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

   通过 --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 If you need to preserve per-platform values.

3. 将文件推送到__CAPGO_KEEP_0__ Actions 秘密 .env file to GitHub Actions secrets

   终端窗口 gh secret set -f 复制到剪贴板 KEY=value 完成了 — 所有您的工作流程所需的秘密现在都在__CAPGO_KEEP_0__中。请使用

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

   它包含明文签名材料。 一旦您将其推送到GitHub: gh secret list.

   file to __CAPGO_KEEP_0__ Actions secrets

   The command reads a dotenv file and creates one repository secret per line: Terminal window Copy to clipboard That’s it — every secret your workflow needs is now in GitHub. Verify with Don’t commit the .env file 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
(added manually)	CAPGO_TOKEN

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

工作流程示例

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

1. 手动触发

允许任何具有写入访问权限的人从 Actions GitHub 的平台下拉菜单中触发构建。适用于按需测试构建或触发发布。

/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 Build 自动增加您的构建号于每次发布构建。如果您愿意将其固定到标签，请参阅 跳过构建号增加 以下。

3. 在主分支推送时构建调试

通过在每次推送到主分支时生成一个调试 Android 构建来尽早捕获本机构建回归。 main. cheap 运行成本低，反馈快，且可以跳过 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

The paths 过滤器确保工作流程不会在仅有文档更改的情况下运行。 --no-playstore-upload 跳过 Play Store 提交（无需），并 PLAY_CONFIG_JSON 生成用于测试设备安装的 APK 下载 URL，以便您可以安装它。 --output-upload 常见模式

标题：常见模式

标题：跳过 Play Store / TestFlight 上传

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

提交商店发布进行审查

默认情况下，发布构建上传签名的工件并将最终商店操作留给您控制。对于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 路径并将处理好的 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 值会退出非零，因此一个过时的 CLI 在 runner 中会大声失败而不是静默地发出一个空的 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	The provisioning map points at a different bundle ID than the one Xcode is signing. Re-run 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或在生成工件之前失败 outputUrl 将会 null 在记录中 [ -n "$URL" ] 在分支上“__CAPGO_KEEP_0__”之前使用它
build last-output __CAPGO_KEEP_0__ 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，它会随着任务而漂浮

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

下一步

凭据设置 iOS 和 Android 凭据的 base64 秘密准备的完整参考资料。

iOS 构建 有关证书、配置文件和 App Store 提交的更深入的指南。

Android Builds 安卓构建

Configuration Options All CLI flags and environment variables for fine-tuning your builds.