GitLab CI/CD 集成

将 Capgo Live Updates 与 GitLab CI/CD 集成，每次推送 code 变更时自动部署应用更新。本指南介绍如何设置自动化构建、测试和部署工作流。

前提条件

在配置 GitLab CI/CD 集成之前，请确保您已准备好：

• 一个包含项目仓库的 GitLab 账号
• 一个已配置好 App 的 Capgo 账号
• 项目中已配置 Node.js 和 npm/yarn

配置 GitLab CI/CD

第 1 步：配置环境变量

首先，在您的 GitLab 项目中设置必要的变量：

1. 前往您的 GitLab 项目
2. 前往 设置 → CI/CD → 变量
3. 添加以下变量：

变量名	值	已保护	已掩码
CAPGO_TOKEN	你的 Capgo API token	✅ 是	✅ 是

提示

从以下地址获取你的 Capgo API token console.capgo.app/apikeys。你的 app ID 已配置在你的 capacitor.config.ts 文件。

基础

每次 push 到 main 分支时都会部署到生产环境的基础配置：

# .gitlab-ci.yml - Simple Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  only:
    - main

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
    # For encrypted uploads, add: --key-data-v2 "$CAPGO_PRIVATE_KEY"
  dependencies:
    - build
  only:
    - main

进阶

特性分支部署

将功能分支部署到测试频道，以便评审和测试：

# Feature branch deployment
deploy_feature:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="feature-$(echo $CI_COMMIT_REF_NAME | sed 's/[^a-zA-Z0-9-]/-/g')"
    - npx @capgo/cli channel add $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - /^feature\/.*$/
  environment:
    name: feature/$CI_COMMIT_REF_NAME
    url: https://your-app.com/channels/$CHANNEL_NAME

提示

使用频道测试在部署到功能频道后，您可以通过将应用配置为使用该特定频道来测试更新。详细了解 在应用中配置频道.

使用加密

如果你在使用 Capgo 的加密功能，你需要将私钥安全地存储在 CI/CD 环境中。

在 设置加密密钥 在本地，将您的私钥添加到 GitLab 变量中：

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

将此内容作为 CAPGO_PRIVATE_KEY 添加到 GitLab 项目变量中（设为 protected 和 masked），然后在 pipeline 中使用：

# Deploy with encryption
deploy_production:
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --key-data-v2 "$CAPGO_PRIVATE_KEY" --channel production

注意

安全最佳实践：

• 切勿将 .capgo_key_v2 文件提交至版本控制系统
• 私钥仅存储在安全的 CI/CD 密钥管理系统中
• 不同环境使用不同密钥

多通道配置

如需全面了解如何设置和管理多个部署渠道，请参阅 Channels 文档.

多环境与 Merge Request 部署的完整配置：

# .gitlab-ci.yml - Advanced Multi-Channel Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

# Build stage
build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 24 hours

# Deploy to development channel
deploy_development:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development
  dependencies:
    - build
  only:
    - develop
  environment:
    name: development

# Deploy merge requests to test channels
deploy_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="mr-$CI_MERGE_REQUEST_IID"
    - npx @capgo/cli channel add $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - merge_requests
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    url: https://your-app.com/channels/mr-$CI_MERGE_REQUEST_IID
    on_stop: cleanup_mr

# Cleanup MR channels when MR is closed
cleanup_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli channel delete mr-$CI_MERGE_REQUEST_IID --apikey $CAPGO_TOKEN || true
  when: manual
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    action: stop
  only:
    - merge_requests

# Deploy to staging
deploy_staging:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging
  dependencies:
    - build
  only:
    - develop
  environment:
    name: staging

# Deploy to production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  environment:
    name: production

带手动审批的多环境

对于需要手动审批的生产环境部署：

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  when: manual
  environment:
    name: production

基于分支的部署策略

自动将不同分支部署到对应的 channel：

# Dynamic channel deployment based on branch
deploy:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - |
      if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
        CHANNEL="production"
      elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then
        CHANNEL="staging"
      else
        CHANNEL="development"
      fi
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL
  dependencies:
    - build
  environment:
    name: $CHANNEL

安全最佳实践

受保护的变量

1. 标记敏感变量: 务必将 API token 标记为受保护且已掩码
2. 分支保护: 在生产环境部署时使用受保护变量
3. 访问控制: 仅限维护人员访问变量
4. 定期轮换定期轮换 API token

安全的 Pipeline 配置

# Use protected variables for production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  only:
    refs:
      - main
    variables:
      - $CI_COMMIT_REF_PROTECTED == "true"

监控与通知

Slack 集成

在您的 pipeline 中添加 Slack 通知：

notify_success:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"✅ Capgo deployment successful for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_success

notify_failure:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"❌ Capgo deployment failed for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_failure

邮件通知

在您的 GitLab 项目设置中配置电子邮件通知，或使用 API：

notify_email:
  stage: .post
  script:
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
        --form "to=team@yourcompany.com" \
        --form "subject=Capgo Deployment Status" \
        --form "body=Deployment of $CI_COMMIT_REF_NAME completed with status: $CI_JOB_STATUS" \
        "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/emails"
  when: always

故障排除

常见问题

Pipeline 报错“Capgo CLI not found”：

# Debug CLI installation
debug_cli:
  script:
    - npm install -g @capgo/cli
    - which capgo || echo "Capgo CLI not found"
    - npx @capgo/cli --version

身份验证错误：

# Verify token configuration
debug_auth:
  script:
    - |
      if [ -z "$CAPGO_TOKEN" ]; then
        echo "CAPGO_TOKEN is not set"
        exit 1
      fi
      echo "Token length: ${#CAPGO_TOKEN}"

找不到构建产物：

# List build outputs
debug_build:
  script:
    - ls -la dist/
    - find dist/ -type f -name "*.js" -o -name "*.html"

Pipeline 调试

添加调试信息以排查问题：

debug:
  stage: build
  script:
    - echo "Branch: $CI_COMMIT_REF_NAME"
    - echo "Commit: $CI_COMMIT_SHA"
    - echo "Build: $CI_PIPELINE_ID"
    - env | grep CI_ | sort
  only:
    - branches

下一步

• 了解 通道 以管理不同的部署环境
• 探索 自定义存储 用于高级部署场景
• 设置 加密 用于安全部署
• 配置 更新行为 以自定义更新的应用方式

借助 GitLab CI/CD 集成，你可以自动化 Capgo 部署，并确保为移动应用用户提供一致、可靠的更新。

继续探索 GitLab CI/CD 集成

如果你正在使用 GitLab CI/CD 集成 规划 CI/CD 自动化，并将其与 Capgo CI/CD 用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成 用于 Capgo 集成中的产品工作流， CI/CD 集成 了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成 有关 GitHub Actions 集成的实现细节。