GitHub 动作

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

您将获得

无人值守发布

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

无本地设置

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

Scoped Secrets

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

并行构建

并行构建

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

在设置工作流程之前，请确保您有：

• 一个Capgo帐户，具有活跃的订阅和一个__CAPGO_KEEP_1__密钥 Capgo API key
• Capgobunx @capgo/cli@latest app add __CAPGO_KEEP_1__
• 本地配置的构建凭证 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. 如果您尚未设置，请先完成此步骤 — 该向导将处理证书创建、配置文件、密钥库和 Play Store 服务帐户的交互式设置。

设置

The Capgo CLI can export your local credentials as a ready-to-use .env __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 可以将您的本地凭据导出为可用的文件。结合 gh secret set -f, 这将整个 CI/CD 设置转换为三条命令 — 无需手动 base64 编码、无需 JSON 处理、无需逐一复制粘贴。

1. 将您的 Capgo API 密钥添加为仓库密钥

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

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

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

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

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

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

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

   需要每个平台的文件吗

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

   共享配置键

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

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

   终端窗口 gh secret set -f 复制到剪贴板 KEY=value 这样就完成了——您的工作流程所需的每个密钥都已存储在__CAPGO_KEEP_0__中。使用

   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.

   不要将 .env 文件提交到仓库

   它包含明文签名材料。 一旦你将它推送到 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

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

工作流程示例

The three examples below cover the most common patterns. They all use the same shape: check out the repo, install dependencies, build the web assets, sync to native, then call Capgo Build with credentials passed as environment variables.

手动触发

允许任何具有写入访问权限的人从触发一个构建 动作 在 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.0__CAPGO_KEEP_0__ 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 跳过Play Store提交（无需），并 --no-playstore-upload 生成用于下载的APK的URL，方便在测试设备上安装 PLAY_CONFIG_JSON 常见模式 --output-upload 常见模式

Section titled “Common Patterns”

跳过Google Play商店/测试飞行上传

对于测试构建，跳过商店提交：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 默认情况下，使用生产轨道（track） release_status: completed. 建议在调用处指定轨道（track） --android-track （或） PLAY_STORE_TRACK，并使用 --android-release-status / PLAY_STORE_RELEASE_STATUS 当需要时：

- 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}"

对于内部完成的发布而不是生产：

- 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 使用 App Store Connect API 键路径，并将处理后的 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

注意

仅提交构建产物的路径。请在 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（换行终止；安全用于 URL=$(...)).
• --field qrCodePngPath 打印 PNG 路径以便将其作为 PR 附件上传。
• --qr 打印渲染的 ASCII QR — 将其放入 PR 评论中的 Markdown code 场所以实现内联扫描。

注意

只有在构建成功时才会写入记录。未支持的 schemaVersion 和未知的 --field 值会退出非零，因此在运行器中出现过时的 CLI 会大声失败而不是静默地发出一个空的 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

缓存依赖

注意

本节内容是关于 GitHub Actions 在CI运行器（本地 Pods/ 和 .gradle Capgo 也会保留 云构建缓存 每个应用程序在构建运行器（默认启用；忽略 cache_key 共享公共缓存）。通过 --cache-key 为了分离RC和生产环境，或 --no-cache 禁用恢复和保存。请参阅 缓存恢复错误：.

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 中，构建成功但应用程序未出现在 bunx @capgo/cli@latest build credentials manage
错误的团队 ID 或应用程序记录在 App Store Connect 中尚未存在。请使用	上传项目后，构建会卡住 node_modules 项目存档过大 — 检查是否正在上传
Provisioning profile doesn't match bundle ID	不是应该默认上传的 build init 配置文件指向的 bundle ID 与 Xcode 签名的不同。重新运行 build credentials manage
以刷新配置文件，然后重新导出时使用	别忘了重新导出并重新推送: 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 使用它之前 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 … 错误与使用较旧的__CAPGO_KEEP_0__而不是最新的记录而产生的错误有关。将生产者和读者都锁定在相同的明确版本（例如（e.g.） @latest，可以漂浮并在任务之间漂移

查看平台特定的构建故障 故障排除指南.

下一步

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

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

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

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

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