CI/CD 集成

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示

将 Capgo integrate 到 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环境，建议将私钥存储为环境变量而不是文件。以下是如何设置它：

获取私钥内容：
终端窗口
```
cat .capgo_key_v2 | pbcopy
```
此操作会将密钥内容复制到您的剪贴板。
将其添加到您的CI/CD环境中：
- GitHub Actions: 添加 CAPGO_PRIVATE_KEY 将其添加到您的仓库密钥中
- GitLab CI: 将其添加为项目设置中的掩码变量
- CircleCI: 将其添加为项目设置中的环境变量
- Jenkins: 将其添加为密文文本凭证

在您的管道中使用它：

- 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管道中的通用过程如下:

生成API密钥: 登录到Capgo控制台并创建一个新的API密钥。该密钥将用于在CI/CD环境中验证CLI。请保密并不要将其提交到您的仓库!
配置 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 }}" 如果使用加密

添加步骤在您的 web 构建之后 upload : 确保步骤在您的 web 构建成功完成后才执行。这确保您始终部署最新的 __CAPGO_KEEP_0__。\n 以下是 __CAPGO_KEEP_1__ Actions 的示例配置:\nupload.yml 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 }}"

语义化发布的版本管理

Capgo推荐的版本管理方式是通过在文件中设置版本号，文件中引入 capacitor.config.ts 文件 package.json:

import pkg from './package.json'

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

此方法允许您:

使用语义化发布（或其他工具）更新 package.json 版本
自动将更新的版本包含在构建中
上传带有正确版本号的包

您的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}"
      }
    ]
  ]
}

此配置文件执行以下操作：

分析提交消息以确定下一个版本号，遵循 Conventional Commits spec。
根据自上次发布以来提交的更改生成发布说明。
更新 CHANGELOG.md 文件中的发布说明。
更新 package.json 版本号，会被您的capacitor.config捕获。
提交更新 CHANGELOG.md, package.json，和其他更改的文件回到仓库。

确保在构建应用之前运行 semantic-release，以便更新的版本从 package.json is included in your build through the capacitor.config.

Auto-bump when the local version is already on Capgo

版本，上传将失败。建议使用 package.json (例如，使用 semantic-release)。当这不是实际的，允许 package.json (for example with semantic-release). When that is not practical, let the CLI pick the next free semver from the channel’s linked bundle, or else the latest remote app version:

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 uses Capgo Cloudflare Workers AI to compare local bundle files against the previous Capgo/channel delta manifest, pick major | minor | patch | metadata, and print a short reason. With no previous Capgo version, AI is skipped and the bump is 修订版.

请勿合并 --auto-bump 与 --bundle / -b。请参阅 bundle upload 参考完整选项列表。

故障排除

If you encounter issues with your Capgo CI/CD integration, here are a few things to check:

如果您遇到与您的 API CI/CD 集成相关的问题，请检查以下几点:API 密钥
: 确保您的 CLI 密钥有效并具有必要的权限。如果使用环境变量，请检查它是否设置正确。: 确保您正在使用最新版本的 Capgo CLI。较旧的版本可能会出现兼容性问题或缺少某些功能。
构建产物: 确认您的Web构建生成了预期的输出文件。 Capgo CLI 需要一个有效的Web构建才能创建一个捆绑包。
网络连接: 检查您的CI/CD环境是否有访问 Capgo 服务器的网络权限。防火墙或代理问题可能会干扰命令。 upload : 如果您仍然遇到问题，请联系 __CAPGO_KEEP_0__ 支持团队，他们可以帮助您排查特定设置中的任何问题。

If you’re still having trouble, reach out to Capgo support for assistance. They can help troubleshoot any issues with your specific setup.

标题：结论

Integrating Capgo into your CI/CD pipeline with proper version management can greatly streamline your development workflow. By automating your deployments and versioning through the capacitor.config approach, you can ship updates faster and with more confidence.

文件中，并使用semantic-release更新 capacitor.config.ts : 确保您正在使用最新版本的 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__。较旧的版本可能会出现兼容性问题或缺少某些功能。 package.json 提供了一个强大可靠的部署流程,使您能够专注于构建优秀功能而不是担心手动发布步骤。

有关更多详细信息，请参阅Capgo和CLI命令和选项。 CLI参考。有关语义发布配置的更深入了解，请参阅.

语义发布文档

快乐部署！

继续CI/CD集成 如果您正在使用 CI/CD集成 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 本机构建为产品工作流程在 Capgo 本机构建中 Capgo 集成为产品工作流程在 Capgo 集成中 GitHub 动作集成为 GitHub 动作集成的实现细节 GitLab CI/CD 集成为 GitLab CI/CD 集成的实现细节