通过 GitHub Actions 实现 Lovable Capgo Live Updates 自动化

您的客户希望在 Lovable 中通过单个按钮即可将更改推送给所有活跃用户。您已经手动验证了更新流程是通畅的：

npx @capgo/cli@latest bundle upload --channel=production --auto-bump

现在缺少的并不是在 Lovable 中增加另一个终端命令。 Lovable 无法在 Publish 时运行 Capgo。 当启用 GitHub 同步时， Publish 会将 commit 推送到你的仓库. GitHub Actions 会为你运行 build 和 bundle upload 后续流程。

本指南仅包含客户端需要进行的一次性手动设置：添加 CAPGO_TOKEN 作为 GitHub secret。对于 workflow 文件，请将现成的 AI 指令复制粘贴到 Lovable（步骤 3）。

Pipeline 工作原理

步骤	角色	操作内容
1	客户端	在 Lovable 中编辑 App 并点击 Publish
2	Lovable	向 GitHub 提交并推送 (通常 `main`)
3	GitHub 操作	`npm ci`, `npm run build`, `bundle upload --auto-bump` 至 Capgo
4	Capgo	该渠道上的活跃设备 `production` 将接收到更新

无需 SSH，无需本地 CLI，配置好密钥后无需额外点击。

前提条件

已连接至 GitHub 的 Lovable 项目 (导出指南)
Capacitor + @capgo/capacitor-updater 在仓库中 (Lovable 到移动端指南)
已在 Capgo 中注册的应用，其 capacitor.config.ts 指向正确的 appId
production channel 且已与用户运行的 build 关联

原因 `--auto-bump`

每次 Capgo upload 都需要一个 全新的唯一 bundle 版本。Lovable Publish 不会自动递增 package.json ，因此如果你重复使用相同的版本，CI 会在第二次 deploy 时失败。

--auto-bump 读取该 channel (或 app) 的最新版本并进行递增。默认级别为 minor。你可以传递 --auto-bump patch 或 --auto-bump major 如果你愿意。

第 1 步 — 创建 Capgo API 密钥

打开 console.capgo.app/apikeys/
创建一个具有应用 bundle upload 权限的 API 密钥
请务必立即复制该密钥。之后你将无法再次查看完整值

请像对待密码一样对待此密钥。切勿将其提交到 Git 或粘贴到 Lovable chat 中。

第 2 步 — 添加 `CAPGO_TOKEN` 在 GitHub 中（唯一的环境变量步骤）

这是你需要发送给 Kuldeep 以及任何拥有该 repo 的客户端的步骤。

打开 Lovable 同步到的 GitHub 仓库
前往设置 → Secrets 与变量 → Actions
点击 新建仓库 Secret
名称： CAPGO_TOKEN
值：粘贴第 1 步中的 Capgo API key
保存

GitHub 会将该 secret 注入 workflow，名称为 ${{ secrets.CAPGO_TOKEN }}。下方的 workflow 将其读取为 CAPGO_TOKEN 用于 Capgo CLI 的环境变量。

如果仓库在您客户的组织下，他们必须在其仓库中添加 secret。您只需要 GitHub 中的 key，无需在 Lovable 设置中配置。

第 3 步 — 将这段 prompt 粘贴到 Lovable

将下方代码块复制到 Lovable 聊天中。如果您的默认分支不是 main，请将 workflow 中的 main 替换为您的分支名称。

Add Capgo Live Updates CI with GitHub Actions.

Create `.github/workflows/capgo-live-updates.yml` (create folders if needed). Start from this YAML, then adapt install/build to this project while keeping Capgo upload + CAPGO_TOKEN secret behavior:

name: Capgo Live Updates

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Upload bundle to Capgo
        run: npx @capgo/cli@latest bundle upload --channel=production --auto-bump
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Rules:
- Do not hardcode any Capgo API key in the repo or in chat.
- The workflow must read CAPGO_TOKEN only from GitHub Actions secrets (`${{ secrets.CAPGO_TOKEN }}`).
- Keep `--auto-bump` on the upload command so each Publish gets a new unique bundle version.
- Prefer the project's real production build script from package.json (for example `npm run build` or `vite build`).
- If package-lock.json is missing, use `npm install` instead of `npm ci`.
- Do not modify app UI or Capacitor config for this task.
- Commit the workflow file so the next Publish pushes it to GitHub.

Lovable 应用更改后，点击发布这样 workflow 就会落到 GitHub。

手动替代方案

如果您不想使用 Lovable 聊天，可以创建 .github/workflows/capgo-live-updates.yml 仅需此 YAML 文件（而非提示词文本）。如果你的项目有所不同，请参照上述规则调整安装/构建步骤，然后提交并推送。

name: Capgo Live Updates

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Upload bundle to Capgo
        run: npx @capgo/cli@latest bundle upload --channel=production --auto-bump
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Vite base 路径： Lovable Vite 应用通常需要 base: './' 在 vite.config.ts 以便资源能在原生壳层中加载。如果用户在 OTA 更新后看到白屏，请让 Lovable 设置 base: './'，重新发布，并让 workflow 重新部署。

加密 Bundle： 如果你使用 Capgo 加密，请添加 CAPGO_PRIVATE_KEY 作为第二个 GitHub secret 并传递 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" 在 upload 步骤中。

第 4 步 — 确认 Publish 触发部署

在 Lovable 中进行一项细微的可视化更改（例如修改按钮标签文本）
点击发布
在 GitHub 上，打开 Actions 并观察 Capgo Live Updates
当任务运行成功（显示为绿色）时，打开你的 Capgo 控制台并确认一个新的 bundle 已在 production channel
在已安装应用的设备上确认变更已送达（根据 channel 设置，可能需要一分钟左右）

✅ 成功： 在 Lovable 中发布 → 运行绿色的 GitHub Action → Capgo 生成新 bundle → 用户收到更新。

故障排除

现象	可能原因	修复
Workflow 未运行	Push 到了非以下分支： `main`	变更 `branches` 在 workflow 中或发布至 `main`
`CAPGO_TOKEN` / 认证错误	Secret 缺失或名称错误	Secret 必须完全匹配 `CAPGO_TOKEN` 在 Actions secrets 下
版本已存在	Upload 使用了相同的 bundle 版本	保留 `--auto-bump` 在 upload 步骤中（或传入 `--auto-bump patch`)
Build 在以下环节失败 `npm ci`	Lockfile 不同步	运行 `npm install` 在本地，请 commit `package-lock.json`，再次发布
上传成功，但显示白屏	错误 `webDir` 或 Vite `base`	匹配 `capacitor.config.ts` `webDir` 构建输出 (`dist` 针对 Vite) 并设置 `base: './'`
用户无法看到更新	Channel 未与构建版本关联	在 Capgo 中，将设备构建版本链接到 `production` 或将 channel 设置为 public

了解更多工作流模式 (feature branches, PR channels, encryption)，请参阅 GitHub Actions 集成.

你可以这样告诉你的客户

把这份清单发给他们：

您已将 Lovable 连接至 GitHub，并在移动端 App 中配置好了 Capgo。
他们需要 添加一个 GitHub secret： CAPGO_TOKEN 使用他们的 Capgo API 密钥（apikeys 页面).
他们需要 点击发布在 Lovable 中，只要他们想让用户接收变更，即可随时操作。
除非他们主动要求，否则 npx @capgo/cli 绝不会在本地运行。

这完全符合他们要求的“一键式体验”：点击 Lovable 中的 Publish 按钮；剩下的交给 GitHub Actions 和 Capgo。

继续探索

将 Lovable 转换为 iOS 和 Android — 如果您尚未封装应用，则需完成完整的 Capacitor + Capgo 配置
通过 GitHub Actions 实现自动构建与发布 — 基于 Tag 的发布与版本更新
GitHub Actions 集成 — 多渠道及 PR 预览渠道
Capgo Live Updates — Channel、回滚及采用率统计