CI/CD Integration

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

CI/CD 集成的好处

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

• 一致性：每次部署都遵循相同的步骤，确保预测性和可重复的过程。这在您有多个团队成员贡献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

虽然具体步骤会根据您的 CI/CD 工具的选择而有所不同，但将Capgo集成到 CI/CD 管道中的通用过程如下：

1. 生成API密钥: 登录到Capgo控制台并创建一个新的API密钥。该密钥将用于在 CI/CD 环境中验证CLI。请保密并不要将其提交到您的仓库!

2. 配置 bundle upload command: 在您的 CI/CD 配置中添加一个步骤，运行带有适当参数的 bundle upload command

   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. 在 web 构建之后添加 upload : 确保protectedTokens upload 成功完成 web 构建后，会自动触发此步骤。这样您就可以始终部署最新的 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 }}"

语义发布的版本管理

使用 Capgo 的推荐方法是将版本号设置在文件中，通过从 capacitor.config.ts 文件中导入 package.json:

import pkg from './package.json'

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

这种方法允许您：

1. 使用语义发布（或其他工具）更新版本号 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 }}

以下是示例 .releaserc 语义发布的配置文件：

{
  "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版本将被您的capacitor.config.捕获。
5. 提交更新的 CHANGELOG.md, package.json，以及任何其他更改的文件回到仓库中。

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

故障排除

如果您遇到与Capgo CI/CD集成的问题，以下是几件事情需要检查：

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

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

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

• 网络连接: 检查您的 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 文档.

Happy 部署!

从CI/CD Integration继续

如果您正在使用 CI/CD Integration 来规划CI/CD自动化，连接它与 Capgo CI/CD 为Capgo CI/CD产品工作流 Capgo 原生构建 为产品工作流程在 Capgo 原生构建中 Capgo 集成 为产品工作流程在 Capgo 集成中 GitHub 动作集成 在 GitHub 动作集成的实现细节中 GitLab CI/CD 集成 在 GitLab CI/CD 集成的实现细节中