CI/CD 集成

将 Capgo integrates 到您的 CI/CD pipeline 中，允许您完全自动化应用程序构建和部署更新的过程。通过利用 Capgo CLI 和 semantic-release，您可以确保一致、可靠的部署，并启用快速迭代。

CI/CD Integration 的好处

• 自动化: 不再需要手动步骤或人为错误。您可以从头到尾自动化整个构建、测试和部署过程。

• 一致性: 每次部署都遵循相同的步骤，确保可预测和可重复的过程。这尤其值得注意，当您有多个团队成员贡献 code 时。

• 更快的迭代: 自动化部署使您可以更频繁地发布更新，并且可以信心满满地发布。无需等待手动 QA 或发布批准。

Capgo CLI

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

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 Actions: 添加 CAPGO_PRIVATE_KEY 到您的仓库密钥
   • GitLab CI: 将其添加为项目设置中的掩码变量
   • CircleCI: 将其添加为项目设置中的环境变量
   • Jenkins: 将其添加为项目设置中的密文文本凭证

3. 在您的管道中使用:

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

注意: --key-data-v2 允许您将私钥内容直接作为字符串传递，使其适合用于CI/CD管道的环境变量，避免创建临时文件。

此命令将当前Web构建上传到指定的频道。您通常会在CI/CD管道的最后一步运行此命令，之后您的Web构建将成功完成。

在CI/CD管道中设置Capgo

While the exact steps will vary depending on your CI/CD tool of choice, the general process for integrating Capgo looks like this:

1. 生成API密钥: 登录Capgo控制台并创建一个新的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 用你想部署的频道替换 ${{ secrets.CAPGO_API_KEY }} 用环境变量来存储你的 API 密钥，并添加 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" 如果使用加密

3. 添加 upload 步骤在你的 web 构建之后：确保步骤在你的 web 构建成功完成之后。这样你就可以始终部署最新的 __CAPGO_KEEP_0__。\n 这里是一个 __CAPGO_KEEP_1__ Actions 的示例配置:\n upload step comes after your web build has completed successfully. This ensures you’re always deploying your latest code.\n Here’s an example configuration for GitHub Actions:\n

   复制到剪贴板

   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 }}"

Version Management with 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. 您的 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 }}

Here’s a sample .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. 分析提交消息以确定下一个版本号，遵循规范提交规范。
2. 根据自从上次发布的提交生成发布说明。
3. 更新 CHANGELOG.md 文件中的新发布说明。
4. 更新 package.json 版本号，会被您的capacitor.config捕获。
5. 将更新的 CHANGELOG.md, package.json,以及任何其他更改的文件提交回仓库。

确保在构建应用之前运行semantic-release，以便从中获取更新的版本号 package.json 通过您的capacitor.config.包含在您的构建中。

故障排除

如果您遇到与Capgo CI/CD 集成相关的问题，请检查以下几点：

• API密钥: 确保您的API密钥有效并具有必要的权限。如果使用环境变量，请检查它是否正确设置。

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

• 构建产物: 确认您的Web构建生成了预期的输出文件。CapgoCLI需要一个有效的Web构建来创建一个捆绑包。

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

如果您仍然遇到问题，请联系Capgo支持团队获取帮助。他们可以帮助您排查特定设置中的任何问题。

结论

正确地管理版本并将Capgo集成到CI/CD管道中，可以显著简化您的开发流程。通过使用capacitor.config方法来自动化您的部署和版本控制，您可以更快速、更自信地发布更新。

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

有关Capgo CLI命令和选项的更多详细信息，请参阅 CLI参考。对于semantic-release配置的更深入了解，请参阅 semantic-release文档.

快乐部署!