CI/CD 集成

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

CI/CD 集成的好处

• 自动化: 无需再进行手动步骤或留下人类错误的空间。您可以从头到尾自动化整个构建、测试和部署流程。

• Consistency: Every deployment follows the same set of steps, ensuring a predictable and repeatable process. This is especially valuable when you have multiple team members contributing code.

• Faster iterations: 自动化部署可以让您以自信心更频繁地发布更新。无需等待手动QA或发布批准。

Capgo CLI

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

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 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. Use it in your pipeline:

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

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

This command uploads the current web build to the specified channel. You’ll typically run this as the last step in your CI/CD pipeline, after your web build has completed successfully.

在CI/CD管道中设置Capgo

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

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

2. Configure the bundle upload 命令: 将一个步骤添加到您的 CI/CD 配置中，运行 bundle upload 命令

   upload.yml

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

   替换 Production 为您要部署的频道 ${{ secrets.CAPGO_API_KEY }} 为持有您的 API 密钥的环境变量 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" 并添加

3. 如果使用加密 upload web构建之后的步骤: 确保 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

   例如，以下是 __CAPGO_KEEP_1__ 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 }}"

复制到剪贴板

The recommended way to handle versioning with Capgo is to set the version in your 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配置文件
5. 提交更新 CHANGELOG.md, package.json,以及任何其他更改的文件回到仓库。

确保在构建应用之前运行semantic-release，以便从 package.json 更新的版本通过capacitor配置文件

故障排除

如果您遇到与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 文档.

快乐部署！

从 CI/CD Integration 中继续

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