capgo-release-workflows

Capgo 发布工作流

搭建端到端发布系统：通过 Capgo OTA 发布 Web 更改、对二进制更改进行原生构建、发布到应用商店，并设置一个 CI 门禁来选择合适的路径。

适用场景

在以下情况下使用：

• 用户希望用一个发布流水线涵盖实时更新、原生构建和应用商店发布。
• 用户希望从托管式发布服务（如 Appflow）迁移到自己掌控的 CI。
• 用户询问“CI 如何判断是否需要发布到应用商店？”

以下情况不适用：

• 用户只需要执行一项操作（上传或推广一个 bundle、请求一次构建）。请使用 capgo-release-management 或 capgo-native-builds。
• 用户正在接入更新器插件。请使用 capgo-live-updates。
• 用户专门从 Ionic Appflow 迁移。请先从 ionic-appflow-migration 开始，然后再回到这里配置流水线。
• 应用不是 Capacitor 应用。

构建模块

领域	技能	关键命令
OTA 更新	capgo-live-updates、capgo-release-management	bundle upload、channel promote
在 Capgo 上进行原生构建	capgo-native-builds	build request
在自己的运行器上进行原生构建	capacitor-ci-cd	Xcode / Gradle / Fastlane
应用商店页面和审核	capacitor-app-store、capacitor-apple-review-preflight	n/a

流程

1. 清点现状（先检查，再汇报）

确认以下信息：

• 使用哪个 CI 系统（.github/workflows、.gitlab-ci.yml、bitbucket-pipelines.yml、azure-pipelines.yml）。
• 是否已安装 @capgo/capacitor-updater，且其主版本与 @capacitor/core 匹配，以及是否调用了 notifyAppReady()。
• 现有的 Capgo 通道（npx @capgo/cli@latest channel list <appId>）和默认通道。
• 原生签名凭据存放在哪里（Capgo 凭据、CI 密钥、Fastlane match）。
• 是否需要上传到应用商店，还是只需内部分发。

向用户报告差距，并在选择 Capgo Build 或用户自己的运行器来进行原生构建之前先征求同意。

2. 定义通道和版本

• 常见通道：development（自行分配）、staging、production（默认）。
• bundle 版本使用 semver。在 CI 中使用 --bundle <ver> 或 --auto-bump patch，并加上 --version-exists-ok。
• 将 production 一次性设为元数据策略，这样每次上传都会记录其原生基线：

npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

3. 添加 OTA 与原生构建的门禁

# After npm ci && npm run build
if git diff --name-only "$BASE" HEAD | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
  TYPE=native
else
  TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]')
fi

releaseType 根据原生包元数据输出 OTA 或 native。它无法检测原生代码的直接更改，因此需要进行 git 路径检查。build needed 是基于退出码的版本：退出码 1 表示需要原生构建，退出码 0 表示 OTA 即可，退出码 2 表示命令执行失败。

4. 接入两个分支

• OTA： 执行 bundle upload --channel staging --fail-on-incompatible --auto-min-update-version，然后手动或经批准执行 channel promote staging production，也可加上 --rollout 10。
• 原生构建： 执行 build request --platform ios|android（Capgo Build）或原生构建任务，然后上传匹配的 bundle，并加上 --auto-min-update-version，以推进通道基线。请勿在此基线上传时传入 --fail-on-incompatible，因为原生包本应有所不同。

完整的 GitHub Actions 和 GitLab 模板：https://capgo.app/docs/builder/ci-ota-or-native/

5. 回滚计划（首次发布前先写下来）

• OTA：执行 channel set production --bundle <previous> 或 --rollout-rollback。使用 --auto-pause-enabled --auto-pause-action rollback 自动暂停。
• 原生构建：应用商店不支持回滚。请发布修复版本，并确保 OTA 仍可修补 Web 层。

6. 密钥

• CAPGO_TOKEN（具有上传权限，遵循最小权限原则）；如果 bundle 已加密，还需要 CAPGO_PRIVATE_KEY。
• 原生签名：通过 Capgo 的 build credentials manage 导出到 .env，然后执行 gh secret set -f。或者继续使用现有的 CI 密钥存储。
• 切勿提交 .capgo、.capgo_key_v2、.capgo-credentials.json 或 .env.capgo.*。

验证

端到端运行一次：

1. 仅涉及 Web 的提交走 OTA 分支。使用 staging 环境的设备获取更新包（npx @capgo/cli@latest app debug <appId>）。
2. 添加或升级原生插件的提交走原生分支。构建成功后，发布到 TestFlight 或 Play 内部测试轨道。
3. 原生版本发布后，对于仅涉及 Web 的更改，bundle releaseType --channel production 会再次返回 OTA。
4. 实际演练一次回滚（channel set --bundle <previous>），确保测试设备收到回滚。

错误处理

• CI 上传失败并提示 No Capgo API key found：未将 CAPGO_TOKEN 导出到该步骤的 env。
• OTA 分支出现 Bundle NOT compatible with production channel：跳过了门控，或 releaseType 针对了不同的 channel 运行。
• 签名失败：先修复凭据（capgo-native-builds、build prescan），再处理流水线逻辑。
• 商店提交失败：拆分 iOS 和 Android 任务，避免一个平台阻碍排查另一个平台的问题。

资源

• CI 中的 OTA 或原生发布：https://capgo.app/docs/builder/ci-ota-or-native/
• CI/CD 集成：https://capgo.app/docs/getting-started/cicd-integration/
• Capgo Build GitHub Actions：https://capgo.app/docs/builder/github-actions/
• 原生 + OTA channel 工作流：https://capgo.app/docs/live-updates/native-ota-channel-workflow/