메인 콘텐츠로 건너뛰기
Capgo - 빌드, 배포, 및 업데이트 Capacitor 앱 Capgo

GitHub 액션

iOS 및 Android 빌드를 직접 GitHub 저장소에서 자동화하세요. 단일 워크플로 파일과 몇 개의 저장소 비밀만 있으면, 팀의 누구도 Mac, Xcode, 또는 Android Studio를 설치할 필요 없이, 푸시, 태그, 또는 수동 트리거로 생성된 서명된, 저장소에 준비된 앱이 있습니다.

GitHub 작업을 위한 Capgo 빌더

받는물

자동화된 릴리스

Git에서 릴리즈 태그를 지정하면 TestFlight 및 Play Store로 자동으로 서명된 iOS 및 Android 바이너리가 제출됩니다.

Local Setup이 설정되지 않습니다.

윈도우 또는 리눅스에서 iOS 빌드를 트리거할 수 있는 개발자도 있습니다. Xcode, 프로비전링 문제, 공유 서명 인증서가 노트북에 떠다니는 문제가 없습니다.

Scoped Secrets

GitHub 저장소 비밀을 통해 인증 정보가 저장되며, 저장소와 워크플로우 러너만이 볼 수 있습니다. 쉽게 회전하고 감사할 수 있습니다.

병렬 빌드

iOS 및 Android 빌드를 동시에 행하는 매트릭스 작업을 사용하여 빌드하세요. 일반적인 릴리스는 10분 이내에 완료됩니다.

Prerequisites

Before setting up the workflow, make sure you have:

A __CAPGO_KEEP_0__ account with an active subscription and a

  • Capgo __CAPGO_KEEP_1__ key Capgo API 키
  • 애플리케이션은 Capgo (bunx @capgo/cli@latest app add 만약 그렇지 않다면
  • __CAPGO_KEEP_0__ bunx @capgo/cli@latest build init — 참조 인증 정보 관리 위치 마법사 가이드를 위한
  • 로컬 빌드가 성공적으로 완료되었습니다 (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debugCI에서 첫 번째 빌드를 디버깅하는 것은 CI의 역할이 아닙니다
  • 위치 GitHub CLI (gh) 설치 및 인증 (gh auth login)

설정

설정

Capgo CLI을 로컬 인증서로 내보낼 수 있습니다. .env 이것을 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__와 combination하면 CI/CD 설정을 3개의 명령어로만 구성할 수 있습니다. gh secret set -f__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키를 저장소 비밀로 추가하세요

  1. Capgo에서 Capgo API 키를 저장소 비밀로 추가하세요.

    API 키는 앱당 인증 저장소에 포함되지 않으므로 수동으로 한 번 추가하십시오.

    클립보드 복사
    gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

    __CAPGO_KEEP_0__ Capgo 대시보드 with 업로드 권한이 있는 사용자 또는 그 이상의 권한이 필요합니다.

  2. 인증 정보를 파일로 내보내려면 .env 파일

    인터랙티브 인증 관리자를 실행하세요:

    터미널 창
    bunx @capgo/cli@latest build credentials manage --appId com.example.app

    페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label). TUI에서CLI은 GitHub Actions에서 생성합니다. .env.capgo.<appId> . __CAPGO_KEEP_0__은 0600 현재 디렉토리에 (읽기 전용으로) mode로 기록합니다 — 예를 들어, .env.capgo.com.example.appiOS 및 Android가 모두 구성되면, 두 플랫폼의 비밀은 동일한 파일 내에 저장됩니다. # === IOS === 그리고 # === ANDROID === 섹션 헤더. iOS 및 Android env-var 이름은 분리되어 있으므로, 그들을 결합하는 것은 충돌이 없습니다.

  3. 푸시하십시오 .env 파일을 GitHub Actions secrets

    The gh secret set -f 명령어는 dotenv 파일을 읽고, 각 줄에 해당하는 레포지토리 시크릿을 생성합니다. KEY=value 터미널 창

    복사하기
    gh secret set -f .env.capgo.com.example.app

    그것은 이제 모든 비공개 정보가 GitHub에 있습니다. 확인하세요 gh secret list.

  4. 워크플로우 파일을 생성하세요

    추가 .github/workflows/capgo-build.yml Capgo는 Voltbuilder와 Capacitor를 비교합니다.

repository에 추가하세요. 필요한 경우에 따라 아래의 세 가지 트리거 패턴 중 하나를 선택하여 빌드 트리거를 설정하세요.

repository의 비밀에 포함되는 항목

repository의 비밀에 포함되는 항목 gh secret set -f 참조

PlatformGitHub Actions
Secrets 생성BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
iOSANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON
AndroidCAPGO_TOKEN

(수동으로 추가)

워크플로우 예시

워크플로우 예시 섹션

다음 세 가지 예시는 가장 일반적인 패턴을 다룹니다. 모두 동일한 형태를 사용합니다: 저장소 확인, 의존성 설치, 웹 자산 빌드, 네이티브 동기화, 그리고 Capgo 빌드에 인증 정보를 환경 변수로 전달합니다.

1. 수동 트리거

1. 수동 트리거 섹션

Actions에서 쓰기 권한이 있는 모든 사람에게 빌드를 시작할 수 있도록합니다. Actions 탭을 GitHub에 있는 플랫폼 드롭다운과 함께 사용하세요. 유용한 테스트 빌드 또는 즉시 릴리스를 위해 사용하세요.

github/workflows/capgo-build-manual.yml
name: Capgo Build (Manual)


on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]


jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest


      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync


      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

Replace com.example.app __CAPGO_KEEP_0__ ID를 입력하세요. 커밋한 후 Actions → Capgo 빌드 (수동) → 워크플로우 실행 2. 태그에 따라 릴리스

태그에 따라 릴리스

태그에 따라 출시

이 설정은 릴리스 명령어로 사용됩니다. v1.4.0__CAPGO_KEEP_0__ git tag v1.4.0 && git push --tags __CAPGO_KEEP_1__

.github/작업 흐름/capgo-빌드-릴리스.yml
name: Capgo Build (Release)


on:
  push:
    tags:
      - 'v*'


jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest


      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}


      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          # Android
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

iOS와 Android를 별도의 실행자에서 병렬로 실행하는 매트릭스입니다. 설정 fail-fast: false iOS 빌드가 실패해도 Android 빌드가 진행 중일 때 취소되지 않으며, 그 반대도 마찬가지입니다. 이 기능은 한 플랫폼이 임시적으로 서명 문제를 겪고 있을 때 유용합니다.

3. 메인 푸시 시 디버그 빌드

3. 메인 푸시 시 디버그 빌드

Capgo는 GitHub Actions를 통해 Native 빌드 회귀를 빠르게 잡아내는 데 도움이 됩니다. mainCheap to run, fast feedback, and you can skip Play Store upload to keep it purely a smoke test.

github/workflows/capgo-build-main.yml
name: Capgo Build (Main)


on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'


jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest


      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android


      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

The paths 필터는 문서 변경만 있을 때 워크플로우가 실행되지 않도록 합니다. --no-playstore-upload Play Store 제출을 생략할 수 있습니다 (필요하지 않습니다) 및 PLAY_CONFIG_JSON 결과 APK의 다운로드 URL을 생성하여 테스트 장치에서 설치할 수 있도록 합니다. --output-upload 일반적인 패턴

일반적인 패턴

Play Store / TestFlight 업로드를 생략

애플 스토어 / 테스트 플라이트 업로드 건너뛰기

Section titled “애플 스토어/테스트 플라이트 업로드 건너뛰기”

테스트 빌드의 경우 스토어 제출을 건너뛰세요: 안드로이드는 --no-playstore-upload를 사용합니다. iOS의 경우 --ios-distribution ad_hoc 모드에서 빌드합니다. (이것은 앱 스토어에 제출하지 않습니다). --output-upload 를 사용하여 이진 파일에 대한 시간 제한된 다운로드 URL을 얻으세요.

스토어 릴리스를 검토하기 위해 제출하세요

Section titled “스토어 릴리스를 검토하기 위해 제출하세요”

기본적으로 릴리스 빌드는 서명된 아티팩트를 업로드하고 최종 스토어 액션을 사용자에게 맡깁니다. CI 릴리스가 직접 스토어 검토 흐름으로 이동해야 하는 경우 --submit-to-store-review.

서비스 계정 PLAY_CONFIG_JSON 을 사용하세요. explicit track이 없으면 --submit-to-store-review 로 기본적으로 프로덕션 트랙이 됩니다. release_status: completed. Prefer stating the track at the site with --android-track (또는 PLAY_STORE_TRACK), 그리고 상태를 override 할 때: --android-release-status / PLAY_STORE_RELEASE_STATUS 필요한 경우:

- name: Submit Android release for review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
    KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
    KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
    KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

내부 완료 릴리스 대신 프로덕션:

- name: Submit Android internal release
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
    KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
    KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
    KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track internal \
      --store-release-name "${GITHUB_REF_NAME}"

iOS는 App Store Connect API 키 경로를 사용하고 TestFlight 빌드를 App Store 리뷰에 제출합니다. 그것은 app_store 배포에 필요합니다. --ios-testflight-groups 외부 베타 배포에 대해는 선택적이지만 App Store 리뷰에 대해 필요하지 않습니다:

- name: Submit iOS build to App Store review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
    APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
    APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
    APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
    APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

빌드 출력 URL 및 QR 코드 code를 읽어보세요.

빌드 출력 URL 및 QR 코드 code를 읽어보세요.

성공 --output-record <path> 빌드 아티팩트 URL 및 QR 코드 code를 디스크에 영구적으로 저장하고, 빌드가 성공하면 그 값을 다시 읽어보세요. build last-outputNo 로그 스크래핑, No 정규 표현식.

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json


- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json JSON 레코드 ( jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt)와 PNG QR 코드 code를 함께 생성합니다. /tmp/build.json.qr.png. build last-output 값을 다시 읽어보세요:

  • --field outputUrl 다운로드 URL만 출력합니다 (줄바꿈이 끝나는 문자열; 로그에 안전합니다). URL=$(...)).
  • --field qrCodePngPath 이미지를 업로드할 수 있는 PR 첨부물로 PNG 경로를 출력합니다.
  • --qr PR 댓글에 내장 스캔 가능성을 위해 Markdown code 구획 내에 렌더링된 ASCII QR 코드를 출력합니다.

빌드 번호 증가를 건너뜁니다.

제목: 빌드 번호 증가를 건너뜁니다.

기본적으로 각 릴리스 빌드는 빌드 번호를 증가시킵니다. Git 태그와 같은 값을 제어할 수 있는 값을 지정하려면 --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version


- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

의존성 캐시

캐시 의존성

bun install JS-의존성 캐시가 거의 이익이 되지 않지만 Capacitor의 네이티브 의존성 (CocoaPods, Gradle)은 더 큰 프로젝트에 대해 캐싱하는 것이 가치가 있습니다:

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

문제 해결

문제 해결
이름가능한 원인
CAPGO_TOKEN is not set비밀 키를 추가하지 않았거나, 작업이 해당 환경/branch 보호에 접근할 수 없습니다 (환경/branch 보호 확인)
iOS / Android 인증서 오류gh secret set -f 실행되지 않았거나, 다른 저장소에 실행된 경우. 확인하려면 gh secret list
cap sync CI에서 실패하지만 로컬에서 작동합니다A native plugin이 없습니다. package.json또는 잊었습니다. bun install 앞서 cap sync
빌드가 성공했지만 앱 스토어 연결에 앱이 나타나지 않습니다.팀 ID가 잘못되거나 앱 레코드가 아직 앱 스토어 연결에 존재하지 않습니다. 로컬로 확인하세요. bunx @capgo/cli@latest build credentials manage
업로드 중 '프로젝트'가 멈추고 있습니다.프로젝트 아카이브가 비정상적으로 크다면, node_modules 업로드되고 있지 않습니다 (기본적으로 업로드되지 않아야 합니다).
Provisioning profile doesn't match bundle ID프로비저닝 맵이 Xcode가 서명하는 다른 번들 ID를 가리키고 있습니다. 다시 실행하여 프로파일을 갱신하고 build init 다시 내보내기: build credentials manage
로컬에서 인증 정보가 변경되었지만 CI가 실패합니다.다시 내보내기하고 다시 푸시하세요: bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
관리자에서 결합된 파일을 쓰기를 거부합니다.플랫폼 간 공유 구성 키가 다르기 때문에 관리자는 경고하고 확인을 요청합니다. 확인을 눌러서 하나가 덮어씌우거나, 플랫폼별로 다시 내보내세요. --platform ios / --platform android
build last-output 공유된 URL이 비어 있습니다.빌드가 실패했습니다. --output-upload빌드가 실패했습니다. 또는 artifact를 생성하기 전에 실패했습니다. outputUrl 이미 기록되어 있습니다. null 이것을 사용하기 전에 branch를 확인하세요. [ -n "$URL" ] 에러가 발생했습니다.
build last-output 에러 Unsupported record schemaVersionThe runner is on an older CLI than the one that wrote the record. Pin both producer and reader to the same explicit version (e.g. bunx @capgo/cli@7.104.0 … 관리자와 실행자가 동일한 버전으로 고정하세요. @latest관리자와 실행자가 동일한 버전으로 고정하세요.

플랫폼에 따른 빌드 실패를 해결하려면 문제 해결 가이드.

다음 단계

다음 단계 섹션
자동 OTA 또는 네이티브 branch CI는 live update 업로드와 Capgo 빌드 사이에 발생합니다.
CI UI에서 트리거 Capgo 빌드를 액션 탭에서 수동으로 실행합니다.
빌드 웹 훅 관리자 대시보드 HTTP 호출에서 동일한 워크플로우를 시작합니다.
인증 설정 iOS 및 Android 인증을 위한 base64 비밀을 준비하는 데 필요한 모든 참조
설정 옵션 모든 CLI 플래그 및 환경 변수를 빌드에 대한 세부 조정을 위해.