GitHub Actions 集成

将 Capgo Live Updates 与 GitHub Actions 集成，以便在推送 code 更改时自动部署您的应用程序更新。 本指南涵盖了使用 GitHub 强大的 CI/CD 平台设置自动构建、测试和部署工作流程。

先决条件

在设置 GitHub Actions 集成之前，请确保您有：

• 一个 GitHub 仓库，其中包含您的应用程序的源 code
• 一个 Capgo 帐户，其中包含已配置的应用程序
• Node.js 和 npm/yarn 已在您的项目中配置
• GitHub Actions 已为您的仓库启用

设置 GitHub 秘密

步骤 1：配置仓库秘密

在您的 GitHub 仓库中设置必要的秘密：

1. 导航到您的 GitHub 仓库
2. 前往 设置 → 密钥和变量 → 工作流程
3. 点击 新建仓库密钥 并添加以下内容:

密钥名称	值
CAPGO_TOKEN	您的Capgo API令牌

提示

从控制台获取您的Capgo API令牌 在console.capgo.app/apikeys处获取令牌您的应用程序ID已经在您的文件中配置 capacitor.config.ts 文件

简单的生产部署

从以下基本配置开始，部署到每次推送到主分支的生产环境:

# Simple GitHub Actions Workflow for Capgo Live Updates
name: Deploy to Capgo

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, test and build
        run: |
          npm ci
          npm run test
          npm run build

      - name: Deploy to Capgo
         run: |
           npm install -g @capgo/cli
           npx @capgo/cli bundle upload --channel production
          env:
            CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
           # For encrypted uploads, add: --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

高级多渠道配置

功能分支部署

将功能分支部署到临时渠道进行测试:

# Feature branch deployment
name: Deploy Feature Branch to Capgo

on:
  push:
    branches:
      - 'feature/**'

jobs:
  deploy-feature:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: |
          npm ci
          npm run test
          npm run build

      - name: Deploy to feature channel
        run: |
          CHANNEL_NAME=$(echo "${{ github.ref_name }}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
          npm install -g @capgo/cli
          npx @capgo/cli channel create $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true
                     npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel $CHANNEL_NAME

使用加密

如果您正在使用 Capgo的加密功能,您需要在CI/CD环境中安全存储您的私钥。

在 设置加密密钥 locally, add your private key to GitHub secrets:

# Display your private key content (copy this output)
cat .capgo_key_v2

复制到剪贴板 CAPGO_PRIVATE_KEY in your GitHub repository secrets, then use it in workflows:

# Deploy with encryption
- name: Deploy to Capgo with Encryption
  run: |
    npm install -g @capgo/cli
    npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" --channel production

注意事项

安全最佳实践：

• 绝不将 .capgo_key_v2 文件添加到版本控制
• 将私钥存储在安全的CI/CD机密管理中
• 为不同环境使用不同的密钥

多渠道配置

有关设置和管理多个部署通道的详细信息，请参阅 渠道文档.

开发、拉取请求和生产部署的完整工作流程：

# Complete multi-environment workflow
name: Deploy to Capgo

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: |
          npm ci
          npm run test
          npm run build

      - uses: actions/upload-artifact@v6
        with:
          name: dist
          path: dist/

  deploy-development:
    if: github.ref == 'refs/heads/develop'
    needs: build
    runs-on: ubuntu-latest
    environment: development
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel development

  deploy-pr:
    if: github.event_name == 'pull_request'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - name: Deploy to PR channel
        run: |
          CHANNEL_NAME="pr-${{ github.event.number }}"
          npm install -g @capgo/cli
          npx @capgo/cli channel create $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel $CHANNEL_NAME

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `🚀 This PR has been deployed to Capgo channel: \`pr-${{ github.event.number }}\`\n\nTo test this update in your app, configure it to use this channel. [Learn how to configure channels →](/docs/live-updates/channels/#configuring-the-channel-in-your-app)`
            })

  deploy-production:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel production

提示

使用频道进行测试: 在将应用程序部署到 PR 或开发频道后，您可以通过配置应用程序使用特定频道来测试更新。 了解更多关于 在应用程序中配置频道.

清理功能频道

自动清理功能频道时删除分支：

name: Cleanup Feature Channels

on:
  delete:

jobs:
  cleanup:
    runs-on: ubuntu-latest
    if: github.event.ref_type == 'branch' && startsWith(github.event.ref, 'feature/')
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Delete Capgo channel
        run: |
          CHANNEL_NAME=$(echo "${{ github.event.ref }}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
          npm install -g @capgo/cli
          npx @capgo/cli channel delete $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true

安全性和最佳实践

环境保护规则

在 GitHub 中设置环境保护规则:

1. 前往 设置 → 环境 在您的仓库
2. 创建环境: development, staging, production
3. 对于生产环境，添加:
   • 必需审阅者: 添加必须审批部署的团队成员
   • : 添加部署前延迟时间（可选）Wait timer
   • 部署分支: 只允许 main 分支

安全密钥管理

使用环境特定的密钥：

# Use different secrets per environment
deploy-production:
  environment: production
  steps:
    - name: Deploy to Production
      run: |
        npx @capgo/cli bundle upload \
          --apikey ${{ secrets.CAPGO_PROD_TOKEN }} \
          --app ${{ secrets.CAPGO_PROD_APP_ID }} \
          --channel production

监控和通知

Slack 集成

将 Slack 通知添加到您的工作流程：

name: Deploy with Notifications

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # ... deployment steps

      - name: Notify Slack on Success
        if: success()
        uses: 8398a7/action-slack@v3
        with:
          status: success
          text: '✅ Capgo deployment successful!'
          fields: repo,message,commit,author,action,eventName,ref,workflow
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

      - name: Notify Slack on Failure
        if: failure()
        uses: 8398a7/action-slack@v3
        with:
          status: failure
          text: '❌ Capgo deployment failed!'
          fields: repo,message,commit,author,action,eventName,ref,workflow
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Discord 集成

向 Discord 发送通知：

- name: Discord notification
  if: always()
  uses: Ilshidur/action-discord@master
  with:
    args: |
      Capgo deployment ${{ job.status }}!
      App: ${{ secrets.CAPGO_APP_ID }}
      Channel: ${{ github.ref_name }}
      Commit: ${{ github.sha }}
  env:
    DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}

电子邮件通知

配置电子邮件通知：

- name: Send email notification
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: 'Capgo Deployment Failed - ${{ github.repository }}'
    to: team@yourcompany.com
    from: ci-cd@yourcompany.com
    body: |
      Deployment failed for ${{ github.repository }}
      Branch: ${{ github.ref_name }}
      Commit: ${{ github.sha }}
      Workflow: ${{ github.workflow }}

故障排除

调试工作流程

添加调试步骤以解决问题：

- name: Debug environment
  run: |
    echo "Node version: $(node --version)"
    echo "NPM version: $(npm --version)"
    echo "Working directory: $(pwd)"
    echo "Files in dist/: $(ls -la dist/ || echo 'No dist directory')"
    echo "Environment variables:"
    env | grep -E "(GITHUB_|CAPGO_)" | sort

- name: Test Capgo CLI
  run: |
    npx @capgo/cli --version
    npx @capgo/cli app debug --apikey ${{ secrets.CAPGO_TOKEN }} --app ${{ secrets.CAPGO_APP_ID }}

常见问题和解决方案

工作流程失败，提示“CAPGO_TOKEN not found”：

- name: Verify secrets
  run: |
    if [ -z "${{ secrets.CAPGO_TOKEN }}" ]; then
      echo "ERROR: CAPGO_TOKEN secret is not set"
      exit 1
    fi
    echo "CAPGO_TOKEN is set (length: ${#CAPGO_TOKEN})"
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

无法找到构建文件：

- name: Debug artifacts
  run: |
    echo "Checking for build artifacts..."
    ls -la dist/ || echo "No dist directory found"
    find . -name "*.js" -o -name "*.html" | head -10

网络连接问题：

- name: Test connectivity
  run: |
    ping -c 3 api.capgo.io || echo "Ping failed"
    curl -I https://api.capgo.io/health || echo "Health check failed"

可重用工作流程

Create reusable workflows for consistency across projects:

.github/workflows/reusable-capgo-deploy.yml

name: Reusable Capgo Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      channel:
        required: true
        type: string
    secrets:
      CAPGO_TOKEN:
        required: true
      CAPGO_APP_ID:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - 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: Deploy to Capgo
        run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload \
            --apikey ${{ secrets.CAPGO_TOKEN }} \
            --app ${{ secrets.CAPGO_APP_ID }} \
            --channel ${{ inputs.channel }}

Use the reusable workflow:

.github/workflows/deploy.yml

name: Deploy App

on:
  push:
    branches: [main, develop]

jobs:
  deploy-dev:
    if: github.ref == 'refs/heads/develop'
    uses: ./.github/workflows/reusable-capgo-deploy.yml
    with:
      environment: development
      channel: development
    secrets:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
      CAPGO_APP_ID: ${{ secrets.CAPGO_APP_ID }}

  deploy-prod:
    if: github.ref == 'refs/heads/main'
    uses: ./.github/workflows/reusable-capgo-deploy.yml
    with:
      environment: production
      channel: production
    secrets:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
      CAPGO_APP_ID: ${{ secrets.CAPGO_APP_ID }}

Next Steps

• Learn about Channels to manage different deployment environments
• 浏览 自定义存储 用于高级部署场景
• 设置 加密 用于安全部署
• 配置 更新行为 以自定义方式应用更新

通过GitHub Actions 集成，您可以利用GitHub强大的CI/CD平台，创建具有内置安全、监控和协作功能的复杂部署工作流程，用于您的Capgo Live Updates。

继续GitHub Actions 集成

If you are using __CAPGO_KEEP_0__ GitHub Actions Integration to plan CI/CD automation, connect it with __CAPGO_KEEP_0__ CI/CD for the product workflow in Capgo CI/CD Capgo Native Builds for the product workflow in Capgo Native Builds Capgo Integrations for the product workflow in Capgo Integrations for the product workflow in Capgo Integrations, for the implementation detail in CI/CD Integration, and GitLab CI/CD Integration __CAPGO_KEEP_0__ 为 GitLab CI/CD Integration 的实现细节。