CI/CD集成

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

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

CI/CD Integration 的好处

自动化: 不再需要手动步骤或人为错误。您可以从头到尾自动化整个构建、测试和部署过程。
一致性: 每次部署都遵循相同的步骤，确保可预测和可重复的过程。这在您有多个团队成员贡献 code 时尤其有价值。
更快的迭代: 自动化部署使您可以更频繁地发布更新，并且可以信心满满地发布。无需等待手动 QA 或发布审批。

Capgo CLI

Capgo CLI 是 CI/CD 流程中整合 Capgo 的关键。它提供了推送新包版本、管理频道等命令。

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

获取您的私钥内容：
终端窗口
```
cat .capgo_key_v2 | pbcopy
```
此操作会将密钥内容复制到您的剪贴板。
将其添加到您的CI/CD环境：
- GitHub 操作: 添加 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 }}" 如果使用加密.

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

版本管理与Semantic-release

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

import pkg from './package.json'

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

这种方法可以让你:

使用semantic-release（或其他工具）来更新 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 规范。
根据上次发布以来提交的修改生成发布说明。
更新 CHANGELOG.md 文件中的发布说明。
更新 package.json 版本号，会被您的capacitor.config捕获。
提交更新 CHANGELOG.md, package.json，以及任何其他更改的文件回到仓库。

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

当本地版本已经在 Capgo 时，自动增加版本号

捆绑包名称必须唯一（删除的版本仍占据其名称）。如果 CI 继续上传相同的版本，上传将失败。建议使用 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 CI/CD 集成相关的问题，请检查以下几点:API 密钥
: 确保您的 CLI 密钥有效并具有必要的权限。如果使用环境变量，请检查它是否正确设置。: Make sure you’re using the latest version of the Capgo CLI. Older versions may have compatibility issues or lack certain features.
构建产物: 确认您的 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参考. And for a deeper dive into semantic-release configuration, see the .并且为了更深入地了解semantic-release配置，请参阅.

semantic-release文档

Happy部署!

标题：继续CI/CD集成 如果您正在使用 CI/CD集成 Capgo CI/CD 连接到产品工作流程中的Capgo CI/CD集成 Capgo 原生构建 Capgo 原生构建中的产品工作流程 Capgo 集成 Capgo 集成中的产品工作流程 GitHub 动作集成 GitHub 动作集成的实现细节 GitLab CI/CD 集成 GitLab CI/CD 集成的实现细节