Azure DevOps 集成

将 Capgo 实时更新与 Azure DevOps Pipelines 集成,以在推送代码更改时自动部署应用更新。本指南涵盖设置自动化构建、测试和部署工作流。

先决条件

在设置 Azure DevOps 集成之前,请确保您具有:

• Azure DevOps 组织和项目
• 配置了应用的 Capgo 账户
• 您的应用源代码在 Azure Repos Git 存储库中
• 在项目中配置的 Node.js 和 npm/yarn

设置 Azure DevOps 管道

步骤 1: 创建管道变量

首先,在 Azure DevOps 项目中设置必要的变量:

1. 导航到您的 Azure DevOps 项目
2. 转到 Pipelines → Library → Variable groups
3. 创建一个名为 Capgo-Variables 的新变量组
4. 添加以下变量:

变量名称	值	安全
CAPGO_TOKEN	您的 Capgo API 令牌	✅ 是

提示

从 console.capgo.app/apikeys 获取您的 Capgo API 令牌。您的应用 ID 已在您的 capacitor.config.ts 文件中配置。

简单配置

在每次推送到主分支时部署到生产的基本配置:

# Capgo 实时更新的简单 Azure DevOps 管道
trigger:
  branches:
    include:
      - main

variables:
  - group: Capgo-Variables

jobs:
  - job: BuildAndDeploy
    displayName: '构建并部署到 Capgo'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - task: NodeTool@0
        displayName: '设置 Node.js'
        inputs:
          versionSpec: '22.x'

      - script: |
          npm ci
          npm run test
          npm run build
        displayName: '安装、测试和构建'

      - script: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --channel production
        displayName: '部署到 Capgo'

高级配置

功能分支部署

将功能分支部署到测试频道以进行审查和测试:

# 功能分支部署
trigger:
  branches:
    include:
      - feature/*

variables:
  - group: Capgo-Variables

jobs:
  - job: DeployFeature
    displayName: '部署功能分支'
    pool:
      vmImage: 'ubuntu-latest'
    condition: startsWith(variables['Build.SourceBranch'], 'refs/heads/feature/')

    steps:
      - task: NodeTool@0
        inputs:
          versionSpec: '22.x'

      - script: |
          npm ci
          npm run test
          npm run build
        displayName: '安装、测试和构建'

      - script: |
          BRANCH_NAME=$(echo "$(Build.SourceBranchName)" | sed 's/[^a-zA-Z0-9-]/-/g')
          CHANNEL_NAME="feature-$BRANCH_NAME"
          npm install -g @capgo/cli
          npx @capgo/cli channel create $CHANNEL_NAME --apikey $(CAPGO_TOKEN) || true
          npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --channel $CHANNEL_NAME
        displayName: '部署到功能频道'

提示

使用频道进行测试: 部署到功能频道后,您可以通过将应用配置为使用该特定频道来测试应用中的更新。了解更多关于 在应用中配置频道 的信息。

使用加密

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

在本地 设置加密密钥 后,将您的私钥添加到 Azure DevOps 变量:

# 显示您的私钥内容(复制此输出)
cat .capgo_key_v2

在您的 Azure DevOps 变量组中将此内容添加为 CAPGO_PRIVATE_KEY(标记为机密),然后在管道中使用它:

# 使用加密部署
- script: |
    npm install -g @capgo/cli
    npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --key-data-v2 "$(CAPGO_PRIVATE_KEY)" --channel production
  displayName: '使用加密部署到 Capgo'

警告

安全最佳实践:

• 永远不要将 .capgo_key_v2 文件提交到版本控制
• 仅在安全的 CI/CD 机密管理中存储私钥
• 为不同的环境使用不同的密钥

多频道配置

有关设置和管理多个部署频道的综合信息,请参阅 频道文档。

具有多个环境和拉取请求部署的完整配置:

# 具有多个频道的高级 Azure DevOps 管道
trigger:
  branches:
    include:
      - main
      - develop

pr:
  branches:
    include:
      - main
      - develop

variables:
  - group: Capgo-Variables

stages:
  # 构建阶段
  - stage: Build
    jobs:
      - job: BuildApp
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '22.x'

          - script: |
              npm ci
              npm run test
              npm run build
            displayName: '安装、测试和构建'

          - task: PublishBuildArtifacts@1
            inputs:
              pathToPublish: 'dist'
              artifactName: 'app-build'

  # 部署到开发环境
  - stage: DeployDev
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/develop'))
    jobs:
      - deployment: DeployDevelopment
        environment: development
        pool:
          vmImage: 'ubuntu-latest'
        strategy:
          runOnce:
            deploy:
              steps:
                - task: NodeTool@0
                  inputs:
                    versionSpec: '22.x'

                - task: DownloadBuildArtifacts@0
                  inputs:
                    artifactName: 'app-build'
                    downloadPath: '$(Pipeline.Workspace)'

                - script: |
                    npm install -g @capgo/cli
                    npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --channel development --path $(Pipeline.Workspace)/app-build
                  displayName: '部署到开发环境'

  # 部署拉取请求到测试频道
  - stage: DeployPR
    condition: and(succeeded(), eq(variables['Build.Reason'], 'PullRequest'))
    jobs:
      - job: DeployPRChannel
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '22.x'

          - task: DownloadBuildArtifacts@0
            inputs:
              artifactName: 'app-build'
              downloadPath: '$(Pipeline.Workspace)'

          - script: |
              CHANNEL_NAME="pr-$(System.PullRequest.PullRequestNumber)"
              npm install -g @capgo/cli
              npx @capgo/cli channel create $CHANNEL_NAME --apikey $(CAPGO_TOKEN) || true
              npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --channel $CHANNEL_NAME --path $(Pipeline.Workspace)/app-build
            displayName: '部署到拉取请求频道'

  # 部署到生产环境
  - stage: DeployProd
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - deployment: DeployProduction
        environment: production
        pool:
          vmImage: 'ubuntu-latest'
        strategy:
          runOnce:
            deploy:
              steps:
                - task: NodeTool@0
                  inputs:
                    versionSpec: '22.x'

                - task: DownloadBuildArtifacts@0
                  inputs:
                    artifactName: 'app-build'
                    downloadPath: '$(Pipeline.Workspace)'

                - script: |
                    npm install -g @capgo/cli
                    npx @capgo/cli bundle upload --apikey $(CAPGO_TOKEN) --channel production --path $(Pipeline.Workspace)/app-build
                  displayName: '部署到生产环境'

多环境部署

对于具有多个环境的复杂场景:

# 具有多个环境的扩展管道
parameters:
  - name: deployEnvironment
    displayName: '部署环境'
    type: string
    default: 'staging'
    values:
      - staging
      - production

variables:
  - group: Capgo-Variables
  - name: channelName
    ${{ if eq(parameters.deployEnvironment, 'production') }}:
      value: 'production'
    ${{ else }}:
      value: 'staging'

stages:
  # 构建阶段
  - stage: Build
    jobs:
      - job: BuildApp
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '22.x'

          - script: |
              npm ci
              npm run test
              npm run build
            displayName: '安装、测试和构建'

          - task: PublishBuildArtifacts@1
            inputs:
              pathToPublish: 'dist'
              artifactName: 'app-build'

  - stage: DeployStaging
    displayName: '部署到测试环境'
    dependsOn: Build
    condition: and(succeeded(), eq('${{ parameters.deployEnvironment }}', 'staging'))
    jobs:
      - deployment: DeployStaging
        displayName: '部署到测试频道'
        pool:
          vmImage: 'ubuntu-latest'
        environment: 'staging'
        strategy:
          runOnce:
            deploy:
              steps:
                - template: deploy-steps.yml
                  parameters:
                    channel: 'staging'

  - stage: DeployProduction
    displayName: '部署到生产环境'
    dependsOn: Build
    condition: and(succeeded(), eq('${{ parameters.deployEnvironment }}', 'production'))
    jobs:
      - deployment: DeployProduction
        displayName: '部署到生产频道'
        pool:
          vmImage: 'ubuntu-latest'
        environment: 'production'
        strategy:
          runOnce:
            deploy:
              steps:
                - template: deploy-steps.yml
                  parameters:
                    channel: 'production'

部署模板 (deploy-steps.yml)

创建可重用的模板文件 deploy-steps.yml:

deploy-steps.yml

parameters:
  - name: channel
    type: string

steps:
  - task: NodeTool@0
    displayName: '安装 Node.js'
    inputs:
      versionSpec: '22.x'

  - task: DownloadBuildArtifacts@0
    displayName: '下载构建工件'
    inputs:
      artifactName: 'app-build'
      downloadPath: '$(System.ArtifactsDirectory)'

  - script: |
      npm install -g @capgo/cli
    displayName: '安装 Capgo CLI'

  - script: |
      npx @capgo/cli bundle upload \
        --apikey $(CAPGO_TOKEN) \
        --channel ${{ parameters.channel }} \
        --path $(System.ArtifactsDirectory)/app-build
    displayName: '上传到 Capgo (${{ parameters.channel }})'

基于分支的部署策略

根据 Git 分支配置不同的部署策略:

trigger:
  branches:
    include:
      - main
      - develop
      - feature/*

variables:
  - group: Capgo-Variables
  - name: targetChannel
    ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
      value: 'production'
    ${{ elseif eq(variables['Build.SourceBranch'], 'refs/heads/develop') }}:
      value: 'staging'
    ${{ else }}:
      value: 'development'

stages:
  - stage: Build
    jobs:
      - job: BuildApp
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '22.x'

          - script: |
              npm ci
              npm run test
              npm run build
            displayName: '安装、测试和构建'

          - task: PublishBuildArtifacts@1
            inputs:
              pathToPublish: 'dist'
              artifactName: 'app-build'

  - stage: Deploy
    displayName: '部署到 $(targetChannel)'
    dependsOn: Build
    condition: succeeded()
    jobs:
      - deployment: DeployJob
        displayName: '部署到 $(targetChannel) 频道'
        pool:
          vmImage: 'ubuntu-latest'
        environment: '$(targetChannel)'
        strategy:
          runOnce:
            deploy:
              steps:
                - template: deploy-steps.yml
                  parameters:
                    channel: '$(targetChannel)'

安全最佳实践

安全变量管理

1. 使用变量组: 在 Azure DevOps 变量组中存储敏感数据
2. 标记为机密: 始终将 API 令牌和密钥标记为机密变量
3. 范围访问: 限制变量组对特定管道和用户的访问
4. 轮换密钥: 定期轮换您的 Capgo API 令牌

监控和通知

Teams 集成

向您的管道添加 Microsoft Teams 通知:

- task: ms-teams-deploy-card@1.4.1
  displayName: '成功时通知 Teams'
  condition: succeeded()
  inputs:
    webhookUri: '$(TEAMS_WEBHOOK_URL)'
    title: 'Capgo 部署成功'
    text: '应用已部署到 $(targetChannel) 频道'
    themeColor: '00FF00'

- task: ms-teams-deploy-card@1.4.1
  displayName: '失败时通知 Teams'
  condition: failed()
  inputs:
    webhookUri: '$(TEAMS_WEBHOOK_URL)'
    title: 'Capgo 部署失败'
    text: '部署到 $(targetChannel) 失败'
    themeColor: 'FF0000'

电子邮件通知

为部署状态配置电子邮件通知:

- task: EmailReport@1
  displayName: '发送电子邮件报告'
  condition: always()
  inputs:
    sendMailConditionConfig: 'Always'
    subject: 'Capgo 部署报告 - $(Build.BuildNumber)'
    to: 'team@yourcompany.com'
    body: |
      部署状态: $(Agent.JobStatus)
      频道: $(targetChannel)
      构建: $(Build.BuildNumber)
      提交: $(Build.SourceVersion)

故障排除

常见问题

管道失败,提示 “找不到 Capgo CLI”:

# 确保全局安装
- script: |
    npm install -g @capgo/cli
    which capgo || echo "未在 PATH 中找到 Capgo CLI"
  displayName: '安装和验证 Capgo CLI'

身份验证错误:

# 验证令牌是否正确设置
- script: |
    echo "令牌长度: ${#CAPGO_TOKEN}"
    if [ -z "$CAPGO_TOKEN" ]; then
      echo "未设置 CAPGO_TOKEN"
      exit 1
    fi
  displayName: '验证 Capgo 令牌'
  env:
    CAPGO_TOKEN: $(CAPGO_TOKEN)

找不到构建工件:

# 列出可用工件用于调试
- script: |
    ls -la $(System.ArtifactsDirectory)
    find $(System.ArtifactsDirectory) -name "*.js" -o -name "*.html"
  displayName: '调试工件'

调试管道

添加调试步骤来解决问题:

- script: |
    echo "Build.SourceBranch: $(Build.SourceBranch)"
    echo "Build.BuildNumber: $(Build.BuildNumber)"
    echo "目标频道: $(targetChannel)"
  displayName: '调试管道变量'

- script: |
    npx @capgo/cli app debug --apikey $(CAPGO_TOKEN)
  displayName: '调试 Capgo 应用状态'

后续步骤

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

通过 Azure DevOps 集成,您可以自动化 Capgo 部署并确保为移动应用用户提供一致、可靠的更新。