GitLab CI/CD 연동

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

사전 요구사항

GitLab CI/CD 연동을 시작하기 전에 다음 사항을 확인하세요:

• 프로젝트 저장소가 있는 GitLab 계정
• 앱이 구성된 Capgo 계정
• 프로젝트에 설정된 Node.js 및 npm/yarn

GitLab CI/CD 설정하기

1단계: 환경 변수 설정

먼저, GitLab 프로젝트에 필요한 변수를 설정하세요:

1. GitLab 프로젝트로 이동
2. 다음으로 이동: 설정 → CI/CD → 변수
3. 다음 변수를 추가하세요:

변수 이름	값	Protected	Masked
CAPGO_TOKEN	Capgo API 토큰	✅ 예	✅ 예

팁

Capgo API 토큰을 다음에서 가져오세요: console.capgo.app/apikeys. 앱 ID는 이미 다음 항목에 설정되어 있습니다: capacitor.config.ts 파일로 저장하세요.

간단

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

# .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로 표시), 파이프라인에서 사용하세요:

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

멀티 채널 설정

여러 배포 채널을 설정하고 관리하는 방법에 대한 자세한 내용은 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

수동 승인이 포함된 Multi-Environment

수동 승인이 필요한 프로덕션 배포의 경우:

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

브랜치 기반 배포 전략

각 브랜치를 적절한 채널에 자동으로 배포하세요:

# 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 토큰은 항상 protected 및 masked로 지정하세요
2. 브랜치 보호: 프로덕션 배포 시 보호된 변수 사용
3. 액세스 제어: 변수 접근 권한을 관리자(Maintainer)로 제한
4. 정기적 교체: API 토큰을 정기적으로 교체

안전한 파이프라인 구성

# 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 연동

파이프라인에 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

문제 해결

자주 발생하는 문제

“Capgo CLI not found” 오류와 함께 Pipeline이 실패하는 경우:

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