Capgo 与 GitHub Actions 集成指南

Capgo 以及 GitHub 操作 共同简化应用的更新部署 Capacitor 。以下是该集成值得关注的原因：

• 节省成本：与 AppFlow 相比，5 年内最多可节省 $26,100 的 CI/CD 成本 AppFlow.
• 快速更新：即时推送更新，95% 的用户可在 24 小时内收到。
• 安全部署: 端到端加密保障更新安全。
• 精简工作流：直接在您的 GitHub 仓库中自动完成构建和部署。

快速概览

1. 要求：GitHub 账户， Capgo 账号 （每月 12 美元起），Capacitor 项目， Node.js.
2. 配置: 安装 Capgo CLI 配合 npx @capgo/cli init，使用 YAML 工作流配置 GitHub Actions。
3. 部署：使用类似 npx @capgo/cli deploy 改为 自动化更新.
4. 测试：在生产环境之前部署到测试渠道（例如 beta、staging）。

示例工作流（YAML）:

name: Capgo Deploy  
on:  
  push:  
    branches:  
      - main  

jobs:  
  deploy:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v6  
      - uses: actions/setup-node@v3  
        with:  
          node-version: '24'  
      - name: Install Dependencies  
        run: npm install  
      - name: Deploy to Capgo  
        run: npx @capgo/cli deploy  
        env:  
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}  

此集成确保应用更新快速、安全且成本效益高，非常适合敏捷开发团队。

GitHub 操作 教程 - 基础概念与 CI/CD 流水线

设置要求

集成 Capgo 与 GitHub Actions 集成需要配置必要的工具和设置。

所需工具和账户

请确保您已准备好以下账户和工具：

配置完成后，即可将 Capgo 添加到项目中，实现自动化 Live Update。

添加 Capgo 到您的项目

要将 Capgo 集成到项目中，请使用其 CLI 工具在 Capacitor 项目中安装它。Capgo 创始人 Martin Donadieu 表示：

“运行 npx @capgo/cli init 即可！” [1]

此命令将配置该插件及其所需依赖项。

GitHub 仓库设置

准备好您的 GitHub 仓库，以满足与 Capgo 进行 CI/CD 集成的要求。

在添加 workflow 之前，请确认仓库已配置好 OTA 发布流程所需的 secrets、分支保护和部署触发器。

定价

• Capgo 方案起步价为 $12/月。
• 同一方案还包含 OTA 更新，以及每月约 15 次 Native Build。
• 额外的构建时长按分钟通过 credits 计费。

下面是设置仓库的步骤：

• 仓库结构: 将 code 源码、资源和配置文件分别放在不同目录中，让项目保持整洁、易于管理。
• 环境配置: 为开发、预发布和生产分别创建独立环境，并确保配置好适当的访问控制和安全措施。
• 访问管理：谨慎设置仓库权限，以允许 Capgo 集成 同时确保安全性。

这些步骤将确保你的项目已准备好使用 GitHub Actions 工作流，下一节将详细介绍。

GitHub Actions 工作流配置

自动化你的 Capgo 部署 使用 GitHub Actions 简化你的 CI/CD 流程。

创建工作流文件

首先在仓库的 .github/workflows 目录中创建一个 YAML 文件。示例如下：

name: Capgo Deploy
on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v3
        with:
          node-version: '24'
      - name: Install Dependencies
        run: npm install
      - name: Build App
        run: npm run build
      - name: Deploy to Capgo
        run: npx @capgo/cli deploy
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

此配置可确保部署安全且自动化。设置好该文件后，为你的工作流选择合适的触发器。

工作流触发选项

GitHub Actions 可让你自定义工作流何时运行。以下是一些触发选项：

管理密钥

为了确保部署安全，您需要妥善管理密钥。GitHub Actions 为此提供了加密的密钥管理系统。

设置安全身份验证的步骤：

1. 进入仓库设置
   前往仓库设置，在 “Security” 选项卡下找到 “Secrets and variables” 部分。

2. 添加 Capgo 凭据
   将您的 Capgo 认证令牌保存为仓库密钥。命名为 CAPGO_TOKEN.

3. 在工作流中引用密钥
   通过以下方式引用已存储的密钥，在工作流中使用它们： ${{ secrets.CAPGO_TOKEN }}.

在 Workflow 中使用 Capgo 命令

配置好 GitHub Actions 环境后，您可以通过集成 Capgo CLI 命令来自动化部署。

安装 Capgo CLI

在您的工作流中添加以下步骤，以安装 Capgo CLI：

steps:
  - name: Install Capgo CLI
    run: npm install -g @capgo/cli
  - name: Initialize Capgo
    run: npx @capgo/cli init

验证 CLI 身份

使用以下方法安全地认证 CLI CAPGO_TOKEN:

- name: Authenticate Capgo CLI
  run: npx @capgo/cli login
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

部署命令

以下是用于构建、版本管理和部署更新的关键命令：

要自动化整个部署流程，可以这样组合使用这些命令：

steps:
  - name: Build and Deploy
    run: |
      npx @capgo/cli build
      npx @capgo/cli version ${{ github.ref_name }}
      npx @capgo/cli deploy
    env:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

此配置可确保每次 workflow 运行时，您的更新都会自动构建、设置版本并部署。GitHub 的密钥管理系统会在整个过程中保障您的凭据安全。

测试与修复

运行测试 workflow

您可以使用专门的工具来测试您的 GitHub Actions workflow Capgo 测试通道。这允许您在更新正式发布前进行验证。

- name: Test Build Deployment
  run: |
    npx @capgo/cli build
    npx @capgo/cli deploy --channel beta
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Capgo 的通道系统可帮助您为不同阶段创建独立的部署路径：

错误解决方案

以下是一些常见的集成问题及解决方法：

1. 身份验证失败

请检查 GitHub Secrets 中的 CAPGO_TOKEN。如果已过期，请重新生成以确保身份验证顺利进行。

2. 构建错误

请确保您的构建配置符合部署环境的要求。

“我们在生产环境中为 5000+ 用户推出了 Capgo OTA 更新。运行非常平稳，OTA 部署到 @Capgo 后几分钟内，几乎所有用户都已更新到最新版本。” [1]

3. 版本冲突

请遵循语义化版本控制并正确递增版本号，以防止部署过程中出现冲突。

维护技巧

• 使用 Capgo 分析 用于监控更新成功率。
• 为可能出问题的更新启用自动回滚。
• 使用 channel 选择器测试 pull requests (PRs)，以便更好地控制。
• 使用最新的 Capgo CLI 命令让 workflow 保持最新。

对于高优先级部署，利用 Capgo 的错误追踪功能及早发现潜在问题。如果出现问题，回滚功能可让你快速恢复到稳定版本，尽量减少中断。这些做法能帮助你的部署在逐步接近生产环境时保持平稳运行。

总结

核心亮点

Capgo 与 GitHub Actions 的集成简化了部署流程，适用于 Capacitor 应用，为开发团队带来显著优势。全球更新成功率达 82%，95% 的活跃用户在 24 小时内收到更新 [1]，该方案以高效著称。

以下是一些亮点功能：

• 自动化工作流：通过直接在 GitHub Actions 中配置工作流，无需外部 CI/CD 托管。与 AppFlow 等替代方案相比，此方法可降低运营成本，五年内节省约 26,100 美元 [1].
• 快速部署：可即时推送更新，绕过应用商店的审核延迟。
• 强大的安全性：端到端加密确保更新安全交付，同时 Capgo 的通道系统支持受控的分阶段发布。

这些功能为更定制化的解决方案和性能提升奠定了基础，下文将深入探讨。

进阶策略

要充分利用 Capgo 和 GitHub Actions 集成，请探索以下高级技巧：

• 自定义 API 工作流：利用 Capgo 公开的 API，设计符合团队具体需求的部署工作流。这可以实现白标体验，并与现有工具无缝集成。 [1].
• 基于 Channel 的发布：利用 Capgo 的 channel 功能实现分阶段、可控的更新，优化部署流程。
• 性能优化：利用 Capgo 的增量更新（partial updates）降低带宽占用并加快更新速度。凭借在 750 个生产应用中交付的 2350 万次更新 [1]，该系统已证明能够应对大规模需求。

为了获得更佳效果，可以考虑使用 Capgo 的自托管选项或自定义 API 配置。请查看前文了解详细的设置和测试指南，以充分落实这些策略。

继续阅读 Capgo 与 GitHub Actions 集成指南

如果你正在使用 Capgo 与 GitHub Actions 集成指南 来规划安全与合规，请结合 加密 了解 Encryption 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 了解 Capgo Security Scanner 的产品工作流， Capgo 安全 用于 Capgo 安全的产品工作流，以及 Capgo 信任中心 用于 Capgo 信任中心的产品工作流。