GitHub GitHub Actions

Automate your iOS and Android builds directly from your GitHub repository. With one workflow file and a handful of repository secrets, every push, tag, or manual trigger can produce signed, store-ready apps — without anyone on the team needing a Mac, Xcode, or Android Studio installed.

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

标题：您将获得

无人值守发布

上下文：Capgo 营销网站。角色：UI 标签。见于：页面 agents/[slug].astro。消息键 `agents_page_copy_label` (Agents Page Copy Label)。

无本地设置

Scoped 秘钥

仓库中的凭据存储在 GitHub 仓库密钥中，仅对工作流程运行器可见。易于旋转，易于审计。

并行构建

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

Prerequisites

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

• 应用程序在 Capgo 中注册（如果尚未注册） Capgo API 密钥
• 您的应用程序在 Capgo (bunx @capgo/cli@latest app add 如果不是)
• Parallel Builds 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 可以将您的本地凭据导出为可直接使用的GitHub Actions。 .env ，整个CI/CD设置就变成了三条命令——无需手动base64编码、无需JSON处理、无需逐一复制粘贴。 gh secret set -f将您的__CAPGO_KEEP_0____CAPGO_KEEP_1__密钥添加为仓库密钥

1. 在 GitHub Actions 中，添加您的 Capgo API 密钥作为仓库密钥。

   The API key isn’t stored in the per-app credential store, so you need to add it manually once.

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   与 Capgo 面板 with 上传 需要或更高权限。

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

   运行交互式凭据管理器:

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

   在 TUI 中选择 导出到 .env. CLI 将 .env.capgo.<appId> 以 (仅可读者) 模式写入您的当前目录 — 例如, 0600 需要或更高权限 .env.capgo.com.example.appiOS 和 Android 都配置了，两者的密钥都会出现在同一个文件下 # === 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 如果您需要保留每个平台的值。

3. 推送到 .env 文件到GitHub Actions 秘密

   该 gh secret set -f 命令读取一个dotenv文件并为每行创建一个存储库秘密： KEY=value 终端窗口

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

   所有的工作流程需要的密钥现在都在 GitHub 中了。请确认 gh secret list.

   不要提交.env文件

   它包含纯文本签名材料。 一旦您将其推送到GitHub:

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

   复制到剪贴板

4. 重新导出任何时候需要旋转凭据 — 文件不是长期存活的艺术品。

   创建工作流文件 .github/workflows/capgo-build.yml 添加

将其添加到您的仓库中。 选择以下三种触发模式之一，根据您希望如何触发构建。

平台 gh secret set -f 参考

Platform	创建的机密
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. 手动触发

让任何具有写入访问权限的人从 Actions tab 在 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 2. 根据标签发布

.github/工作流程/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. 在主分支推送时调试构建

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

通过每次推送都生成一个调试 Android 构建来尽早捕捉本地构建回归问题。 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

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

常见模式

跳过 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 服务帐户。 没有明确的跟踪 --submit-to-store-review 默认为生产跟踪 release_status: completed. Prefer 在调用站点中明确指定跟踪 --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}"

iOS 使用 App Store Connect __CAPGO_KEEP_0__ 键路径并将处理的 TestFlight 构建提交到 App Store 审核。它需要

- 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 key path，并将处理好的 TestFlight 版本提交至 App Store 评审。它需要 app_store distribution; --ios-testflight-groups 注意

- 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 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	可能原因
未添加密钥，或者作业无法访问它（检查环境/分支保护）	gh secret set -f 缺少 iOS / Android 凭证错误 gh secret list
cap sync 未运行，或者在不同的仓库中运行。请参见	A native plugin 不存在 package.json, 或您忘记了 bun install 之前 cap sync
应用构建成功，但在 App Store Connect 中未显示应用	构建成功，但应用程序在 App Store Connect 中未出现 bunx @capgo/cli@latest build credentials manage
错误的团队 ID，或者应用程序记录尚未在 App Store Connect 中存在。 验证本地使用	构建卡住在“上传项目”之后 node_modules 项目存档过大 — 检查是否正在上传 (它不应该默认上传)
Provisioning profile doesn't match bundle ID	配置文件指向的 bundle ID 与 Xcode 签名的不同。 重新运行 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 与 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__上。将生产者和读者都锁定在相同的显式版本上（例如 @latest在两边都使用相同的版本）而不是

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

下一步

Auto OTA 或 Native live update 和 Capgo 之间的 Branch CI

从 CI UI 触发 从 Actions 选项卡手动触发 Capgo 构建

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

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

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