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 }}"

注意：: 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的配置:\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 version, which will be picked up by your 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 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 Builder / 原生云构建产品页面。角色：短UI标签或导航项。消息键`native_build_feature_ci_cd`（Native Build Feature Ci Cd）。）计划CI/CD自动化，连接它到Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 本机构建为产品工作流程在 Capgo 本机构建中 Capgo 集成为产品工作流程在 Capgo 集成中 GitHub 动作集成为实现细节在 GitHub 动作集成中， GitLab CI/CD 集成为实现细节在 GitLab CI/CD 集成中。