Bitbucket Pipelines 集成

Integrate Capgo Live Updates with Bitbucket Pipelines to automatically deploy your app updates whenever you push code changes. This guide covers setting up automated builds, testing, and deployment workflows.

先决条件

在设置 Bitbucket Pipelines 集成之前，请确保您有:

• 一个 Bitbucket 帐户和一个仓库
• 一个 Capgo 帐户配置了一个应用
• 在您的项目中配置了 Node.js 和 npm/yarn

设置 Bitbucket Pipelines

步骤 1：配置存储库变量

首先，在 Bitbucket 存储库中设置必要的变量：

1. 导航到您的 Bitbucket 存储库
2. 前往 存储库设置 → 管道 → 存储库变量
3. 添加以下变量:

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

提示

Get your Capgo API token from console.capgo.app/apikeys中获取您的__CAPGO_KEEP_0__ __CAPGO_KEEP_1__令牌。 capacitor.config.ts 您的应用程序 ID 已在您的文件中配置。

简单

基本配置，推送到主分支时即部署到生产环境：

# bitbucket-pipelines.yml - Simple Configuration
image: node:22

pipelines:
  branches:
    main:
      - step:
          name: Build and Deploy to Production
          script:
            - npm ci
            - npm run test
            - npm run build
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
          artifacts:
            - dist/**

高级

特性分支部署

将特性分支部署到测试频道进行审查和测试：

# Feature branch deployment
pipelines:
  branches:
    feature/*:
      - step:
          name: Deploy Feature Branch
          script:
            - npm ci
            - npm run test
            - npm run build
            - BRANCH_NAME=$(echo $BITBUCKET_BRANCH | 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
          artifacts:
            - dist/**

提示

测试与频道: 在将应用程序部署到特定频道后，您可以通过配置应用程序使用该特定频道来测试更新。了解有关在应用程序中配置频道的更多信息 配置频道.

使用加密

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

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

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

将此内容添加为 CAPGO_PRIVATE_KEY 在您的 Bitbucket 仓库变量中（标记为安全），然后在管道中使用它：

# Deploy with encryption
- step:
    name: Deploy to Capgo with Encryption
    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 秘密管理中存储私钥
• 为不同环境使用不同的密钥

多渠道配置

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

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

# bitbucket-pipelines.yml - Advanced Multi-Channel Configuration
image: node:22

definitions:
  steps:
    - step: &build-step
        name: Build Application
        script:
          - npm ci
          - npm run test
          - npm run build
        artifacts:
          - dist/**

    - step: &deploy-step
        name: Deploy to Capgo
        script:
          - npm install -g @capgo/cli
          - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME

pipelines:
  branches:
    main:
      - step:
          <<: *build-step
      - step:
          <<: *deploy-step
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - export CHANNEL_NAME=production
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME

    develop:
      - step:
          <<: *build-step
      - step:
          <<: *deploy-step
          name: Deploy to Development
          deployment: development
          script:
            - export CHANNEL_NAME=development
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME

  pull-requests:
    '**':
      - step:
          <<: *build-step
      - step:
          name: Deploy PR to Test Channel
          script:
            - CHANNEL_NAME="pr-$BITBUCKET_PR_ID"
            - 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
          artifacts:
            - dist/**

多环境管道

有关包含测试和生产环境的复杂部署方案的信息：

# Multi-environment pipeline
image: node:22

pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - npm ci
            - npm run test
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production

    develop:
      - step:
          name: Build and Deploy to Development
          script:
            - npm ci
            - npm run test
            - npm run build
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development
          artifacts:
            - dist/**

分支部署策略

自动将不同分支部署到适当的渠道：

# Dynamic channel deployment
image: node:22

definitions:
  scripts:
    - script: &determine-channel |
        if [ "$BITBUCKET_BRANCH" = "main" ]; then
          export CHANNEL_NAME="production"
        elif [ "$BITBUCKET_BRANCH" = "develop" ]; then
          export CHANNEL_NAME="staging"
        else
          export CHANNEL_NAME="development"
        fi
        echo "Deploying to channel: $CHANNEL_NAME"

pipelines:
  default:
    - step:
        name: Build and Deploy
        script:
          - npm ci
          - npm run test
          - npm run build
          - *determine-channel
          - npm install -g @capgo/cli
          - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
        artifacts:
          - dist/**

并行管道执行

通过并行步骤来优化构建时间：

# Parallel execution pipeline
image: node:22

pipelines:
  branches:
    main:
      - parallel:
          - step:
              name: Run Tests
              script:
                - npm ci
                - npm run test
          - step:
              name: Lint Code
              script:
                - npm ci
                - npm run lint
      - step:
          name: Build Application
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production

安全最佳实践

仓库变量

1. : 总是将 __CAPGO_KEEP_0__ 标记为安全变量: Always mark API tokens as secured
2. 并行管道执行: 使用部署特定的变量时需要
3. 访问控制: 限制对授权团队成员的存储库访问
4. 令牌轮换: 定期轮换您的 Capgo API 令牌

部署环境

配置部署环境以获得更好的安全性：

# Deployment with environment restrictions
pipelines:
  branches:
    main:
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production

监控和通知

Slack 集成

将 Slack 通知添加到管道中：

# Pipeline with Slack notifications
pipelines:
  branches:
    main:
      - step:
          name: Build and Deploy
          script:
            - npm ci
            - npm run test
            - npm run build
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
          after-script:
            - |
              if [ $BITBUCKET_EXIT_CODE -eq 0 ]; then
                curl -X POST -H 'Content-type: application/json' \
                  --data '{"text":"✅ Capgo deployment successful for '$BITBUCKET_BRANCH'"}' \
                  $SLACK_WEBHOOK_URL
              else
                curl -X POST -H 'Content-type: application/json' \
                  --data '{"text":"❌ Capgo deployment failed for '$BITBUCKET_BRANCH'"}' \
                  $SLACK_WEBHOOK_URL
              fi

电子邮件通知

通过 Bitbucket 内置功能或使用外部服务配置电子邮件通知：

# Email notification step
- step:
    name: Send Notification
    script:
      - |
        curl -X POST \
          -H "Content-Type: application/json" \
          -d '{
            "to": "team@yourcompany.com",
            "subject": "Capgo Deployment Status",
            "body": "Deployment of '$BITBUCKET_BRANCH' completed with status: '$BITBUCKET_EXIT_CODE'"
          }' \
          $EMAIL_SERVICE_URL
    condition:
      result: [successful, failed]

故障排除

常见问题

管道因“Capgo CLI 未找到”而失败：

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

认证错误：

# Verify token configuration
- step:
    name: 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
- step:
    name: Debug Build
    script:
      - ls -la dist/
      - find dist/ -type f -name "*.js" -o -name "*.html"

调试管道

添加调试信息以解决问题：

# Debug pipeline
pipelines:
  branches:
    main:
      - step:
          name: Debug Information
          script:
            - echo "Branch: $BITBUCKET_BRANCH"
            - echo "Commit: $BITBUCKET_COMMIT"
            - echo "Build: $BITBUCKET_BUILD_NUMBER"
            - env | grep BITBUCKET_ | sort
      - step:
          name: Build and Deploy
          script:
            - npm ci
            - npm run test
            - npm run build
            - npm install -g @capgo/cli
            - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production

管道验证

启用管道验证以捕获配置错误：

# Enable pipeline validation
options:
  docker: true
  size: 2x

pipelines:
  branches:
    main:
      - step:
          name: Validate Pipeline
          script:
            - echo "Pipeline validation successful"
      - step:
          name: Build and Deploy
          script:
            # ... deployment steps

下一步

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

通过 Bitbucket Pipelines 集成，您可以自动部署您的 Capgo 应用并确保您的移动应用用户始终获得最新、可靠的更新。

继续使用 Bitbucket Pipelines 集成

如果您正在使用 Bitbucket Pipelines 集成 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 为 Capgo CI/CD 产品工作流程 Capgo 原生构建 为Capgo原生构建的产品工作流程 Capgo集成 为Capgo集成的产品工作流程 CI/CD集成 为CI/CD集成的实现细节 GitHub动作集成 为GitHub动作集成的实现细节