GitHub 动作

复制一个安装步骤和完整的Markdown指南的设置提示。

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

What You Get

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

无本地设置

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

范围内的密钥

密钥存储在__CAPGO_KEEP_0__仓库密钥中，仅对工作流运行器可见，范围仅限于您的仓库。易于旋转、易于审计。

Credentials live in GitHub repository secrets, scoped to your repo and visible only to the workflow runner. Easy to rotate, easy to audit.

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

前提条件

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

一个 Capgo 帐户具有活跃的订阅和一个 Capgo __CAPGO_KEEP_1__ 密钥 Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add Managing Credentials
了解更多关于向导教程 bunx @capgo/cli@latest build init 成功的本地构建（）— CI 不是调试您的第一个构建的地方成功的本地构建（）— CI 不是调试您的第一个构建的地方成功的本地构建（）— CI 不是调试您的第一个构建的地方
成功的本地构建（）— CI 不是调试您的第一个构建的地方bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug成功的本地构建（）— CI 不是调试您的第一个构建的地方
The GitHub CLI (gh) 已安装并验证 (gh auth login)

Setup

The Capgo CLI 可以将您的本地凭据导出为可用的 .env 文件。结合 gh secret set -f, 这将整个 CI/CD 设置转换为三个命令 — 无需手动 base64 编码、无需 JSON 处理、无需复制粘贴秘密。

添加您的Capgo API密钥作为仓库密钥

API密钥不属于每个应用程序的凭据存储，因此请手动添加一次：
终端窗口
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
在"__CAPGO_KEEP_0__控制台"中 Capgo dashboard __CAPGO_KEEP_0__ 上传或更高权限
导出您的凭据到一个 .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 === 标题

通过 (或 )来限定管理器到一个平台。然后，导出会产生一个类似于 --platform ios 当 iOS 和 Android 秘密存储在不同的仓库或环境中时，非常有用。 --platform android共享配置键 .env.capgo.com.example.app.ios共享配置键

推送 BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION文件到 __CAPGO_KEEP_0__ Actions 秘密 --platform Push the file to __CAPGO_KEEP_0__ Actions secrets
Push the file to __CAPGO_KEEP_0__ Actions secrets .env Push the file to GitHub Actions secrets

Push the file to __CAPGO_KEEP_0__ Actions secrets 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.*
在需要旋转凭据时重新导出文件 — 文件不是一个长期存活的艺术品。
创建工作流文件

添加到您的仓库中。选择以下三种触发模式中的一个，根据您希望如何触发构建来决定。 .github/workflows/capgo-build.yml 您想要的构建触发模式

什么会出现在您的密钥中

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

平台	创建的密钥
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 使用环境变量传递凭据的构建。

1. 手动触发

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

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 替换。提交后，转到 Actions → Capgo Build (Manual) → 运行工作流 以触发它。

2. 根据标签发布

在推送一个版本标签（如v1.0）时，会并行构建和发布两个平台。 v1.4.0这是最常见的生产环境设置 — git tag v1.4.0 && git push --tags 变成你的发布命令。

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构建（反之亦然）—当一个平台出现临时签名问题时，这很有用。

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

通过在每次推送到 main产生一个调试Android构建来捕捉本机构建回归。

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 filter 确保工作流程不会在 doc-only 变更时运行。 --no-playstore-upload 跳过 Play Store 提交（无需），并且 PLAY_CONFIG_JSON 生成一个下载 URL 以便于在测试设备上安装 APK 文件。 --output-upload 常见模式

标题：常见模式

标题：跳过 Play Store / TestFlight 上传

;对于 iOS，使用 ad-hoc 模式进行构建（这永远不会提交到 App Store）。结合 --no-playstore-upload以获取有限期的下载 URL 以便于获取二进制文件。 --ios-distribution ad_hoc Common Patterns --output-upload Skip Play Store / TestFlight upload

提交应用商店发布到审核

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

Android 使用您的 PLAY_CONFIG_JSON 服务账户并将 Google Play 发布提交到应用商店审核流程，而不是保持其处于空闲状态。添加 --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

读取构建输出 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=$(...)).
--field qrCodePngPath 打印 PNG 路径以便将其作为 PR 附件上传。
--qr 打印渲染的 ASCII QR — 将其放入 PR 评论中的 Markdown code 场所以实现内联扫描。

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

Copy to clipboard --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依赖缓存已经足够快了，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`	配置文件指向的 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`在两边都使用相同的版本）而不是

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

下一步

凭据设置 __CAPGO_KEEP_0__

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

Android构建 Keystore设置、Play Store服务帐户和风味处理。

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