Bitbucket Pipelines 연동

code 변경 사항을 푸시할 때마다 Capgo Live Updates를 통해 앱 업데이트를 자동으로 배포하도록 Bitbucket Pipelines와 연동하세요. 이 가이드에서는 자동 빌드, 테스트 및 배포 워크플로우 설정 방법을 다룹니다.

사전 요구사항

Bitbucket Pipelines 연동을 설정하기 전에 다음 사항을 확인하세요:

• 리포지토리가 있는 Bitbucket 계정
• 앱이 구성된 Capgo 계정
• 프로젝트에 설정된 Node.js 및 npm/yarn

Bitbucket Pipelines 설정하기

1단계: Repository 변수 설정

먼저, Bitbucket 리포지토리에 필요한 변수를 설정하세요:

1. Bitbucket 리포지토리로 이동
2. 다음으로 이동: 리포지토리 설정 → Pipelines → 리포지토리 변수
3. 다음 변수를 추가하세요:

변수 이름	값	보안
CAPGO_TOKEN	Capgo API 토큰	✅ 예

팁

다음에서 Capgo API 토큰을 가져오세요: console.capgo.app/apikeys. 앱 ID는 이미 다음에 설정되어 있습니다: capacitor.config.ts 다운로드됩니다.

간단

main 브랜치에 push할 때마다 프로덕션에 배포하는 기본 설정:

# 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 배포

리뷰 및 테스트를 위해 피처 브랜치를 테스트 채널에 배포하세요:

# 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 add $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 secret 관리에만 저장하세요
• 환경별로 서로 다른 키를 사용하세요

멀티 채널 구성

여러 배포 채널을 설정하고 관리하는 자세한 내용은 Channels 문서.

여러 환경 및 pull request 배포를 포함한 전체 설정:

# 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 add $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

보안 모범 사례

Repository 변수

1. 보안 변수: API 토큰은 항상 보안 설정하세요
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 not found” 오류로 실패:

# 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 Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.