SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场capgo-release-workflows

capgo-release-workflows

部署与运维

查看项目

更新于 10-14 09:28

技能介绍

Capgo Release Workflows 用于为 Capacitor 应用搭建一套完整的发布体系：用 Capgo OTA 承载 Web 层改动，用原生构建处理二进制改动，配合商店发布，并在 CI 中设立一道判断闸门来选择合适的发布路径。

适用时机 当用户希望用一条发布流水线同时覆盖热更新、原生构建和商店发布时使用；当用户准备从托管式发布服务（Appflow 风格）迁移到自有的 CI 时使用；当用户询问“CI 怎么判断这次是否需要走商店发布”时使用。 不适用于：只需要单一操作（上传或推广 bundle、请求一次构建）的场景，此时应使用 capgo-release-management 或 capgo-native-builds；接入 updater 插件时使用 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。
  • 自有 runner 上的原生构建：capacitor-ci-cd，使用 Xcode / Gradle / Fastlane。
  • 商店列表与审核：capacitor-app-store、capacitor-apple-review-preflight。

操作步骤

  1. 盘点现状（先检查再汇报）：确认运行的是哪种 CI 系统（.github/workflows、.gitlab-ci.yml、bitbucket-pipelines.yml、azure-pipelines.yml）；是否安装了与 @capacitor/core 主版本匹配的 @capgo/capacitor-updater，以及是否调用了 notifyAppReady()；现有 Capgo 渠道（npx @capgo/cli@latest channel list <appId>）及默认渠道；原生签名存放位置（Capgo 凭据、CI secrets、Fastlane match）；是否必须上传商店，还是仅内部分发。向用户报告缺口，并在选择 Capgo Build 还是自有 runner 之前先询问用户。
  2. 定义渠道与版本：常见渠道为 development（自分配）、staging、production（默认）。使用 semver bundle 版本；在 CI 中可用 --bundle <ver> 或 --auto-bump patch，并加上 --version-exists-ok。为 production 一次性设置 metadata 策略，使每次上传都记录其原生基线：npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata
  3. 加入 OTA 与原生分支的判断闸门：在 npm ci && npm run build 之后，用 git diff 检查改动是否触及 ios/、android/、capacitor.config 等路径，若触及则走 native，否则通过 bundle releaseType 命令输出 OTA 或 native。releaseType 依据原生包元数据判断，无法感知未提交的原生改动，因此需要 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）或对应原生 job，随后上传匹配的 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.*。

验证方式：端到端跑一次——纯 Web 提交走 OTA 分支，staging 设备能收到 bundle（npx @capgo/cli@latest app debug <appId>）；新增或升级原生插件的提交走原生分支，构建成功并进入 TestFlight 或 Play internal track；原生发布后 bundle releaseType --channel production 对纯 Web 改动重新返回 OTA；做一次演练回滚（channel set --bundle <previous>）能到达测试设备。

错误处理：CI 上传报 No Capgo API key found 说明 CAPGO_TOKEN 未导出到该步骤环境；OTA 分支报 Bundle NOT compatible with production channel 说明闸门被跳过或 releaseType 针对了不同渠道；签名失败应先修凭据（capgo-native-builds、build prescan）再动流水线逻辑；商店失败应把 iOS 与 Android job 拆开，避免一个平台阻塞另一个平台的排查。

资源：OTA 或原生 CI 选择 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 渠道工作流 https://capgo.app/docs/live-updates/native-ota-channel-workflow/。