CI/CD 集成

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

将 Capgo integrate 到 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 命令，带有适当的参数：
自动部署
```
- 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 }}" 如果使用加密。

添加步骤在你的web构建之后： upload 确保步骤在你的web构建完成后才执行。这确保你始终部署最新的__CAPGO_KEEP_0__。这里是__CAPGO_KEEP_1__ Actions的示例配置:\nCopy to clipboard 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 规范。
根据自上次发布以来提交的修改生成发布说明。
更新 CHANGELOG.md 文件中的新发布说明。
更新 package.json version, which will be picked up by your capacitor.config.
__CAPGO_KEEP_0__ CHANGELOG.md, package.json更新后的文件，及任何其他修改的文件，提交回仓库。

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

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

Bundle 名称必须唯一（删除版本仍占据其名称）。如果 CI 持续上传相同的 package.json 终端窗口 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 使用Capgo Cloudflare Workers AI 与本地 bundle 文件进行比较，检测与上一个Capgo/channel 版本之间的差异。 major | minor | patch | metadata自动部署并打印一个简短的原因。没有之前的Capgo版本，AI会被跳过，仅进行版本更新。 patch.

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

故障排除

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

API 键API密钥
CLI 版本确保您正在使用最新的Capgo CLI版本。较旧的版本可能存在兼容性问题或缺少某些功能。
构建产物: 确认您的Web构建正在生成预期的输出文件。Capgo CLI需要一个有效的Web构建来创建一个捆绑包。
网络连接: 检查您的CI/CD环境是否有Capgo服务器的网络访问权限。防火墙或代理问题可能会干扰命令。 upload 命令

: 如果您仍然遇到问题，请联系Capgo支持团队，他们可以帮助您排查特定设置中的任何问题。

结论

将Capgo集成到CI/CD管道中并使用合适的版本管理可以显著简化您的开发流程。通过自动化您的部署和版本管理，使用capacitor.config方法，您可以更快地发布更新并更有信心。

推荐的方法是将版本设置在您的 capacitor.config.ts 文件中，并使用semantic-release更新 package.json 提供了一个可靠的部署过程，使您可以专注于构建优秀功能，而不必担心手动发布步骤。

对于更多关于Capgo CLI命令和选项的信息，请参阅 CLI参考查看更深入的semantic-release配置，请参见 . 并且对于更深入的semantic-release配置，请参阅.

semantic-release 文档

Happy 部署!

标题：继续CI/CD集成 如果您正在使用 CI/CD集成 Capgo 持续集成/持续交付连接它到Capgo CI/CD集成 Capgo 原生构建 Capgo 原生构建 Capgo 集成 Capgo 原生构建 GitHub 动作集成 GitHub 动作集成 GitLab CI/CD 集成 __CAPGO_KEEP_0__