跳过内容
Capgo - Capacitor 应用实时更新 Capgo

GitHub 动作

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

您将获得

标题：您将获得

无人值守发布

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

无本地设置

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

Scoped 秘密

凭据存储在 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)

设置

设置

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-readable only) — 例如 .env.capgo.com.example.app. 当 iOS 和 Android 都配置时，两个平台的密钥会存储在同一个文件下 # === IOS === 和 # === ANDROID === 标题

  3. 命令读取一个dotenv文件并为每行创建一个仓库秘密： .env file to GitHub Actions secrets

    复制到剪贴板 gh secret set -f 就这样 — 所有您的工作流程需要的秘密现在都在__CAPGO_KEEP_0__中。使用 KEY=value 不要将.env文件提交

    Push the file to __CAPGO_KEEP_0__ Actions 秘密
    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.

  4. 创建工作流文件

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

最终会出现在您的密钥

标题：最终会出现在您的密钥

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

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

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

工作流程示例

标题：工作流程示例

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

1. 手动触发

标题：1. 手动触发

允许任何具有写入访问权限的人从触发一个构建 动作 在 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. 根据标签发布

标题：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 构建（反之亦然）——有用当一个平台有暂时的签名问题。

Debug Build on Push to Main

3. 在主分支推送时生成调试版

通过在每次推送时生成调试版 Android 应用来捕捉本机构建回归问题。成本低，反馈快，可以跳过 Play Store 上传以保持纯粹的烟雾测试。 main__CAPGO_KEEP_0__/workflows/__CAPGO_KEEP_1__-build-main.yml

.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

跳过 Play Store 提交（不需要），并 paths 生成用于下载的 APK 的 URL，以便您可以在测试设备上安装它。 --no-playstore-upload 常见模式 PLAY_CONFIG_JSON 常见模式 --output-upload Section titled “Common Patterns”

Section titled “3. Debug Build on Push to Main”

Section titled “Common Patterns”

跳过 Google Play 商店 / TestFlight 上载

标题：跳过 Google Play 商店 / TestFlight 上载

对于测试构建，跳过商店提交：Android 使用 --no-playstore-upload;对于 iOS，使用 ad-hoc 模式进行构建（从未提交到 App Store）。结合 --ios-distribution ad_hoc 以获取对二进制文件的时间限制下载 URL。 --output-upload 提交商店发布进行审查

标题：提交商店发布进行审查

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

Android 使用您的 --submit-to-store-review.

服务帐户。 PLAY_CONFIG_JSON 没有明确的跟踪时 Without an explicit track, --submit-to-store-review 以生产轨道为默认值 release_status: completed. 在调用位置中优先指定轨道 --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

读取构建输出 URL 和 QR code

标题：读取构建输出 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 圈内以实现内联扫描。

默认情况下，每个发布构建都会增加构建号。要将其固定到您控制的值（例如 Git 标签），请传递

复制到剪贴板

__CAPGO_KEEP_0__ --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 Capacitor的本地依赖项（CocoaPods，Gradle）对于较大的项目来说是值得缓存的，但JS依赖项缓存很少会带来收益，因为缓存依赖项的速度已经足够快了：

- 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 isn’t in package.json或你忘記了 bun install 前面 cap sync
在 GitHub Actions 中，建構成功但 App Store Connect 中的應用程式未出現錯誤的團隊 ID，或應用程式記錄尚未在 App Store Connect 中建立。請使用 bunx @capgo/cli@latest build credentials manage
建構掛起在 “上傳專案”專案檔案過大 — 檢查是否正在上傳 (它不應該預設上傳) node_modules 授權配置指向的 bundle ID 與 Xcode 正在簽署的不同。重新執行
Provisioning profile doesn't match bundle ID重新整理配置檔案，然後重新匯出 build init 本地端的憑證變更，但 CI 還是失敗 build credentials manage
不要忘記重新匯出並重新推送：create_an_issue_and_discuss_before_working_on_a_new_feature 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 schemaVersionThe 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构建
构建Webhooks 从管理员控制台HTTP调用启动相同的工作流
凭证设置 iOS和Android凭证的base64密钥的完整参考
配置选项 所有 CLI flags 和环境变量，用于微调您的构建。