GitHub 动作

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

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

您将获得什么

无人值守发布

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

无本地设置

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

范围内的密钥

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

并行构建

使用矩阵作业同时构建iOS和Android。典型发布时间小于10分钟。

前置条件

一个__CAPGO_KEEP_0__帐户，具有活跃的订阅和__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_0__中 bunx @capgo/cli@latest build init 在__CAPGO_KEEP_0__中管理凭据为向导教程
成功的本地构建 (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 可以将您的本地凭据导出为可直接使用的文件。结合 .env ，这使整个CI/CD设置变为三条命令——无需手动base64编码、无需JSON处理、无需逐一复制粘贴密钥。 gh secret set -f将您的 __CAPGO_KEEP_0__ __CAPGO_KEEP_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 dashboard 并上传 permissions or higher.
Export your credentials to a .env file

Run the interactive credentials manager:
Terminal window
```
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 如果您需要保留每个平台的值。
推送到__CAPGO_KEEP_0__ Actions secrets .env file to GitHub Actions secrets

终端窗口 gh secret set -f 复制到剪贴板 KEY=value 这样就完成了 — 所有您的工作流程所需的密钥都已存储在__CAPGO_KEEP_0__中。请使用
不要将.env文件提交到版本控制
```
gh secret set -f .env.capgo.com.example.app
```
它包含明文签名材料。一旦您将其推送到GitHub: gh secret list.
file to __CAPGO_KEEP_0__ Actions secrets
It contains plaintext signing material. Once you’ve pushed it to 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`
(added manually)	`CAPGO_TOKEN`

不需要记住这些 — 下面工作流程例子已经包含了所有它们。

工作流程例子

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

1. 手动触发

允许任何具有写入权限的人从 Actions tab in GitHub with a platform dropdown. Useful for ad-hoc test builds or kicking off a release on demand.

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

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. 在主分支推送时构建调试

通过在每次推送到主分支时生成一个调试 Android 构建来尽早捕获本机构建回归。 main. 低成本运行，快速反馈，并且可以跳过 Play Store 上传以保持它纯粹的烟雾测试。

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。

读取构建输出URL和QR code

Pass --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 标签），请传递 --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已经足够快了，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`	Xcode 签名的 bundle ID 与配置文件指向的不同。重新运行 `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" ]` 在
`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 和 Android 凭据的 base64 秘密的准备全参考。

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

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

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