CI/CD 통합

Capgo를 CI/CD 파이프라인에 통합하면 앱 업데이트 빌드 및 배포 프로세스를 완전히 자동화할 수 있습니다. Capgo CLI와 semantic-release를 활용하면 일관되고 안정적인 배포를 보장하고 빠른 반복 개발을 가능하게 합니다.

CI/CD 통합의 장점

• 자동화: 더 이상 수동 단계나 인적 오류가 없습니다. 빌드, 테스트, 배포 프로세스 전체를 엔드투엔드로 자동화할 수 있습니다.

• 일관성: 모든 배포가 동일한 단계를 따르므로 예측 가능하고 반복 가능한 프로세스를 보장합니다. 여러 팀 구성원이 code에 기여할 때 특히 유용합니다.

• 더 빠른 반복: 자동화된 배포를 통해 더 자주, 자신 있게 업데이트를 출시할 수 있습니다. 더 이상 수동 QA나 릴리스 승인을 기다릴 필요가 없습니다.

Capgo CLI

Capgo CLI은 CI/CD 워크플로우에 Capgo를 통합하는 핵심입니다. 새 번들 버전 푸시, 채널 관리 등 다양한 명령을 제공합니다.

CI/CD 통합에서 가장 중요한 명령은 bundle upload:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

암호화를 사용하는 경우 다음 방법 중 하나로 제공해야 합니다:

프라이빗 키 파일 경로 사용:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

프라이빗 키 내용을 직접 사용 (CI/CD 권장):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

환경 변수 사용 (CI/CD 베스트 프랙티스):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

암호화를 위한 환경 변수 설정

CI/CD 환경에서는 파일을 대신해 개인 키를 환경 변수로 저장하는 것이 좋습니다. 설정 방법은 다음과 같습니다:

1. 개인 키 내용을 가져오세요:

   cat .capgo_key_v2 | pbcopy

   이 명령은 키 내용을 클립보드에 복사합니다.

2. CI/CD 환경에 추가하세요:

   • GitHub 작업: 추가하세요 CAPGO_PRIVATE_KEY 리포지토리 시크릿에 추가하세요
   • GitLab CI: 프로젝트 설정에서 마스킹된 변수로 추가하세요
   • CircleCI: 프로젝트 설정에서 환경 변수로 추가하세요
   • Jenkins를: 시크릿 텍스트 자격 증명으로 추가하세요

3. 파이프라인에서 사용하세요:

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

참고: --key-data-v2 플래그는 개인 키 내용을 문자열로 직접 전달할 수 있어, 임시 파일을 생성하지 않고 환경 변수를 사용하는 CI/CD 파이프라인에 적합합니다.

이 명령은 현재 웹 빌드를 지정된 채널에 업로드합니다. 일반적으로 웹 빌드가 성공적으로 완료된 후 CI/CD 파이프라인의 마지막 단계로 실행합니다.

CI/CD 파이프라인에 Capgo 설정하기

사용하는 CI/CD 도구에 따라 구체적인 단계는 다르지만, Capgo를 통합하는 일반적인 과정은 다음과 같습니다:

1. API 키 생성: Capgo 대시보드에 로그인해 새로운 API 키를 만드세요. 이 키는 CI/CD 환경에서 CLI 인증에 사용됩니다. 반드시 비밀로 유지하고 저장소에 커밋하지 마세요!

2. 다음 항목 구성 bundle upload 명령어: CI/CD 설정에 다음을 실행하는 단계를 추가하세요 bundle upload 명령어를 적절한 인자와 함께 실행합니다:

   upload.yml

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

   를 Production 배포하려는 채널로 교체하세요, ${{ secrets.CAPGO_API_KEY }} API 키를 포함하는 환경 변수와 함께, 그리고 추가 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" 암호화를 사용하는 경우.

3. 다음을 추가하세요 upload 웹 빌드 단계 이후: 다음을 확인하세요. upload 단계가 웹 빌드가 성공적으로 완료된 후에 실행되도록 하세요. 이렇게 하면 항상 최신 code를 배포할 수 있습니다. GitHub Actions의 예시 구성은 다음과 같습니다:

   upload.yml

   name: Deploy to Capgo
    on:
     push:
      branches: [main]
   
   jobs:
    deploy:
    runs-on: ubuntu-latest
   
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
     with:
      node-version: '24'
   
    - run: npm ci
    - run: npm run build
   
    - run: npm install -g @capgo/cli
    - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Semantic-release를 이용한 버전 관리

Capgo에서 버전 관리를 위한 권장 방법은 버전 정보를 capacitor.config.ts 파일에 가져와서 설정하는 것입니다. package.json:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... other config
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

이 방식으로 다음을 할 수 있습니다:

1. semantic-release(또는 다른 도구)를 사용해 업데이트하세요 package.json 버전
2. 업데이트된 버전이 자동으로 포함되도록 앱을 빌드하세요
3. 올바른 버전으로 번들을 업로드하세요

CI/CD 워크플로우는 다음과 같습니다:

- run: npm ci
- run: npx semantic-release  # Updates package.json version
- run: npm run build         # Builds with new version from capacitor.config
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

다음은 .releaserc semantic-release용 설정 파일 예시입니다:

{
  "branches": [
    "main",
    {
      "name": "beta",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

이 설정은 다음을 수행합니다:

1. Conventional Commits 스펙에 따라 커밋 메시지를 분석하여 다음 버전 번호를 결정합니다.
2. 마지막 릴리스 이후의 커밋을 바탕으로 릴리스 노트를 생성합니다.
3. 업데이트: CHANGELOG.md 파일을 새 릴리스 노트로 업데이트합니다.
4. 업데이트: package.json 버전이며, 이는 capacitor.config에서 인식됩니다.
5. 업데이트된 CHANGELOG.md, package.json및 기타 변경된 파일을 저장소에 다시 커밋합니다.

앱을 빌드하기 전에 semantic-release를 실행하여, 업데이트된 버전이 package.json 에서 capacitor.config를 통해 빌드에 포함되도록 하세요.

로컬 버전이 이미 Capgo에 있으면 자동 bump

Bundle 이름은 고유해야 합니다(삭제된 버전도 이름을 계속 차지합니다). CI가 계속 같은 package.json 버전을 업로드하면 업로드가 실패합니다. 버전을 올리는 것이 좋습니다( package.json 예: semantic-release 사용). 현실적으로 어려우면 CLI이 채널에 연결된 bundle에서 다음 사용 가능한 semver를 선택하게 하거나, 아니면 최신 원격 앱 버전을 선택하게 하세요:

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

--auto-bump ai Capgo Cloudflare Workers AI를 사용해 로컬 bundle 파일을 이전 Capgo/채널 delta 파일과 비교해 선택하고, major | minor | patch | metadata짧은 이유를 출력합니다. 이전 Capgo 버전이 없으면 AI는 건너뛰고 bump는 patch는.

함께 사용하지 마세요 --auto-bump 포함 --bundle / -b. 구현 세부 사항은 bundle upload 참조 전체 옵션 목록을 확인하세요.

문제 해결

Capgo CI/CD 통합에 문제가 발생하면 다음 사항을 확인하세요:

• API 키: API 키가 유효하고 필요한 권한이 있는지 확인하세요. 환경 변수를 사용하는 경우 올바르게 설정되었는지 다시 확인하세요.

• CLI 버전: Capgo CLI의 최신 버전을 사용 중인지 확인하세요. 구버전은 호환성 문제나 특정 기능 누락이 있을 수 있습니다.

• 빌드 아티팩트: 웹 빌드가 예상된 출력 파일을 생성하는지 확인하세요. Capgo CLI은 번들을 생성하려면 유효한 웹 빌드가 필요합니다.

• 네트워크 연결: CI/CD 환경이 Capgo 서버에 네트워크 접근이 가능한지 확인하세요. 방화벽 또는 프록시 문제가 간섭을 일으킬 수 있습니다. upload 명령어만 실행하면 됩니다.

여전히 문제가 해결되지 않았다면 Capgo 지원팀에 문의해 주세요. 특정 설정과 관련된 문제를 해결하는 데 도움을 받을 수 있습니다.

마치며

적절한 버전 관리를 통해 CI/CD 파이프라인에 Capgo을 통합하면 개발 워크플로우를 크게 간소화할 수 있습니다. capacitor.config 방식을 통해 배포와 버전 관리를 자동화하면 업데이트를 더 빠르고 확신 있게 배포할 수 있습니다.

권장 방식은 파일에서 버전을 설정한 뒤 capacitor.config.ts semantic-release로 업데이트하는 것이며, package.json 이 방식은 견고하고 신뢰할 수 있는 배포 프로세스를 제공하여, 수동 릴리스 단계를 걱정하는 대신 훌륭한 기능 개발에 집중할 수 있게 해줍니다.

Capgo CLI 명령어와 옵션에 대한 자세한 내용은 CLI 레퍼런스를 확인해 보세요. semantic-release 설정을 더 자세히 알아보려면 semantic-release 문서.

즐거운 배포 되세요!

CI/CD 통합 다음 단계

사용 중이라면 CI/CD 통합 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항에 대해서는, 그리고 GitLab CI/CD 연동 GitLab CI/CD 통합의 구현 세부 사항