CI/CD集成

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

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

获取私钥内容：
终端窗口
```
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 }}"

注意：: The --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 }}" 如果使用加密

添加步骤 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 }}"

语义化发布的版本管理

推荐使用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工作流程应该是这样的:

protectedTokens

- 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 当本地版本已经是 capacitor 时，自动增加版本号。

标题：当本地版本已经是 Capgo 时，自动增加版本号。

版本，上传将失败。建议使用 package.json (例如，使用 semantic-release)。当这不是实际的时，允许 __CAPGO_KEEP_0__ 自动选择下一个可用的 semver，从频道的捆绑包中，或者是最新的远程应用版本： 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 key: Ensure your API key is valid and has the necessary permissions. If using an environment variable, double check that it’s set correctly.
CLI version: 确保您正在使用最新版本的 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集成的实现细节