CI/CD 集成

将 Capgo 集成到您的 CI/CD pipeline 中，可以实现应用构建与更新部署的全自动化。通过结合使用 Capgo CLI 和 semantic-release，您可以确保部署的一致性与可靠性，并实现快速迭代。

CI/CD 集成的优势

• 自动化：告别手动操作，减少人为错误。您的整个构建、测试和部署流程都可以实现端到端自动化。

• 一致性：每次部署都遵循相同的步骤，确保流程可预测且可重复。当有多个团队成员参与 code 时，这一点尤为重要。

• 更快的迭代速度：通过自动化部署，您可以更频繁、更自信地发布更新。无需再等待手动 QA 或发布审批。

Capgo CLI

Capgo CLI 是将 Capgo 集成到您的 CI/CD 工作流中的关键。它提供了推送新 bundle 版本、管理 channels 等命令。

CI/CD 集成中最重要的命令是 bundle upload:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

如果您使用了加密，可以通过以下方式之一提供：

使用私钥文件路径：

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

直接使用私钥内容（CI/CD 环境推荐）：

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

使用环境变量（CI/CD 最佳实践）：

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

配置加密环境变量

对于 CI/CD 环境，建议将私钥存储为环境变量而非文件。配置步骤如下：

1. 获取私钥内容：

   cat .capgo_key_v2 | pbcopy

   这会将密钥内容复制到剪贴板。

2. 将其添加到您的 CI/CD 环境中：

   • GitHub 操作: 添加 CAPGO_PRIVATE_KEY 到您的仓库 Secrets 中
   • GitLab CI: 在项目设置中将其添加为掩码变量 (masked variable)
   • CircleCI: 在项目设置中将其添加为环境变量
   • Jenkins: 将其添加为 Secret Text 凭据

3. 在你的 pipeline 中使用：

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

注意： --key-data-v2 flag 允许你直接将私钥内容作为字符串传递，非常适合在 CI/CD pipeline 中使用环境变量，无需创建临时文件。

该命令会将当前的 web build 上传到指定的 channel。通常你会将其作为 CI/CD pipeline 的最后一步，在 web build 成功完成后运行。

在 CI/CD Pipeline 中设置 Capgo

具体步骤会因你选择的 CI/CD 工具而异，但集成 Capgo 的大致流程如下：

1. 生成 API 密钥：登录 Capgo dashboard 并创建一个新的 API 密钥。该密钥将用于在 CI/CD 环境中对 CLI 进行身份验证。请务必保密，切勿将其提交到代码仓库！

2. 配置 bundle upload 命令：在你的 CI/CD 配置中添加一个步骤，运行 bundle upload 命令并传入相应参数：

   upload.yml

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

   \n 将 Production 替换成你想部署到的 channel， ${{ secrets.CAPGO_API_KEY }} 将包含 API 密钥的环境变量，并添加 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" 如果使用了加密。

3. 添加 upload 步骤应在 Web build 之后: 确保 upload 步骤在 Web build 成功完成后执行。这能确保你始终部署最新的 code。\n以下是 GitHub Actions 的配置示例：\n

   upload.yml

   name: Deploy to Capgo
    on:
     push:
      branches: [main]
   
   jobs:
    deploy:
    runs-on: ubuntu-latest
   
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
     with:
      node-version: '24'
   
    - run: npm ci
    - run: npm run build
   
    - run: npm install -g @capgo/cli
    - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

使用 Semantic-release 进行版本管理

处理 Capgo 版本管理的推荐方式是在你的 capacitor.config.ts 文件中通过从以下路径导入来设置版本 package.json:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... other config
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

这种方式可以让你：

1. 使用 semantic-release（或其他工具）来更新 package.json 版本
2. 构建应用并自动包含更新后的版本
3. 上传带有正确版本的 bundle

你的 CI/CD 工作流如下所示：

- run: npm ci
- run: npx semantic-release  # Updates package.json version
- run: npm run build         # Builds with new version from capacitor.config
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

这是一个 .releaserc semantic-release 的配置示例：

{
  "branches": [
    "main",
    {
      "name": "beta",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

该配置实现了以下功能：

1. 遵循 Conventional Commits 规范，通过分析 commit message 来确定下一个版本号。
2. 根据自上次发布以来的 commits 自动生成 release notes。
3. 更新 CHANGELOG.md 文件中的新 release notes。
4. 更新 package.json 版本号，该版本号将被你的 capacitor.config 识别。
5. 将更新后的 CHANGELOG.md, package.json以及其他任何变更的文件 commit 回仓库。

Make sure to run semantic-release before building your app so that the updated version from package.json 将来自 capacitor 的更新版本包含在构建中。

当本地版本已在 Capgo 上时自动跳过版本更新

Bundle 名称必须唯一（已删除的版本仍占用该名称）。如果 CI 持续上传相同的 package.json 版本，上传将会失败。建议通过递增版本号来 package.json （例如使用 semantic-release）。如果无法实现，请让 CLI 从该 channel 关联的 bundle 中自动选择下一个可用的 semver，或者选择最新的远程 App 版本：

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

--auto-bump ai 使用 Capgo Cloudflare Workers AI 将本地 bundle 文件与之前的 Capgo/channel 增量文件进行对比，选择 major | minor | patch | metadata，并打印简短的原因。如果没有之前的 Capgo 版本，则跳过 AI 并执行递增 patch 版本.

请勿合并 --auto-bump 配合 --bundle / -b。查看 bundle upload 引用 查看完整的选项列表。

故障排除

如果您在 Capgo CI/CD 集成中遇到问题，请检查以下几项：

• API 密钥：确保您的 API key 有效且拥有必要的权限。如果使用环境变量，请再次确认其设置是否正确。

• CLI 版本：确保您正在使用最新版本的 Capgo CLI。旧版本可能会存在兼容性问题或缺少某些功能。

• 构建产物：确认您的 Web build 正在生成预期的输出文件。Capgo CLI 需要有效的 Web build 来创建 bundle。

• 网络连接：检查您的 CI/CD 环境是否可以访问 Capgo 服务器。防火墙或代理问题有时会干扰 upload 命令。

如果问题仍然存在，请联系 Capgo 支持团队寻求帮助。他们可以协助排查您特定环境下的任何问题。

总结

通过合理的版本管理将 Capgo 集成到您的 CI/CD pipeline 中，可以极大地简化开发工作流。通过使用 capacitor.config 方法实现部署和版本控制的自动化，您可以更快速、更自信地发布更新。

推荐的方法是在您的 capacitor.config.ts 文件中设置版本，并使用 semantic-release 来更新 package.json 这提供了一个稳健且可靠的部署流程，让您可以专注于构建出色的功能，而不必担心手动发布步骤。

有关 Capgo CLI 命令和选项的更多详情，请查看 CLI 引用。若要深入了解 semantic-release 配置，请参阅 semantic-release 文档.

祝部署顺利！

继续探索 CI/CD 集成

如果你正在使用 CI/CD 集成 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成 用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成 用于 Capgo 集成中的产品工作流， GitHub Actions 集成 有关 GitHub Actions 集成中的实现细节，以及 GitLab CI/CD 集成 有关 GitLab CI/CD 集成中的实现细节。