수동 릴리즈
Git에서 릴리즈 태그를 지정하면 TestFlight 및 Play Store로 자동으로 제출되는 signed iOS 및 Android 바이너리가 생성됩니다.
GitHub 액션
복사할 수 있는 설정 지시
iOS 및 Android 빌드를 직접 GitHub 저장소에서 자동화하세요. 단일 워크플로 파일과 몇 개의 저장소 비밀만 있으면, 팀의 누구도 Mac, Xcode, 또는 Android Studio를 설치할 필요 없이, 푸시, 태그, 또는 수동 트리거로 생성된 모든 signed, 저장소에 준비된 앱이 자동으로 제출됩니다.
받는물
설정로컬 설정이 필요하지 않습니다.
Windows 또는 Linux에서 iOS 빌드를 트리거할 수 있는 기여자
Scoped Secrets
GitHub 저장소 비밀에 인증 정보가 저장되어 있습니다. 이 인증 정보는 워크플로우 러너만 볼 수 있는 저장소와 워크플로우와 관련된 저장소에만 적용됩니다. 인증 정보를 쉽게 회전하고 감사할 수 있습니다.
Parallel Builds
iOS와 Android를 동시에 빌드할 수 있습니다. 일반적인 릴리스는 10분 이내에 완료됩니다.
Prerequisites
설정하기 전에 다음을 확인하세요:__CAPGO_KEEP_0__ 계정과 활성 구독이 있는 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키
- Capgo에 앱을 등록했습니다. (만약 그렇지 않다면) Capgo API key
- Credentials live in Capgo repository secrets, scoped to your repo and visible only to the workflow runner. Easy to rotate, easy to audit.
bunx @capgo/cli@latest app addBuild iOS and Android at the same time with a matrix job. A typical release finishes in under 10 minutes. - __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ (
bunx @capgo/cli@latest build init설치 및 인증 ( 주의 주의 - 아래의 흐름은 로컬 인증 정보 저장소에 이미 존재하는 인증 정보가 이미 존재하는 것으로 가정합니다 (
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ ( - __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ ( GitHub CLI (
gh) __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ (gh auth login)
설정
설정The Capgo CLI can export your local credentials as a ready-to-use .env 설정 gh secret set -f__CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 로컬 인증서로 export할 수 있습니다.
-
Capgo API
API __CAPGO_KEEP_1__
__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"클립보드 복사 Capgo 대시보드 GitHub Actions을 사용하여 업로드 권한이 있는 사용자 또는 높은 권한이 있는 사용자.
-
인증 정보를 파일로 내보내세요.
.env파일인터랙티브 인증 관리자를 실행하세요:
터미널 창 bunx @capgo/cli@latest build credentials manage --appId com.example.appTUI에서 Export to .env. The CLI writes
.env.capgo.<appId>.env 파일이 현재 디렉토리에 __CAPGO_KEEP_0__로 생성됩니다.0600(owner-readable only) — 예를 들어.env.capgo.com.example.app. iOS와 Android가 모두 구성되면, 두 플랫폼의 비밀은 동일한 파일 아래에 저장됩니다.# === IOS ===및# === ANDROID ===섹션 헤더입니다. iOS와 Android env-var 이름은 겹치지 않기 때문에 combine하는 것은 충돌이 없습니다. -
명령어는 dotenv 파일을 읽고, 각 줄에 대해 하나의 repository secret를 생성합니다.
.envfile to GitHub Actions secrets클립보드에 복사
gh secret set -f그것만으로도 — 모든 워크플로우가 필요로 하는 비밀은 이제 __CAPGO_KEEP_0__에 있습니다. Verify withKEY=value.env 파일은 커밋하지 마세요text gh secret set -f .env.capgo.com.example.appThat’s it — every secret your workflow needs is now in GitHub. Verify with
gh secret list. -
워크플로우 파일을 생성하세요.
추가
.github/workflows/capgo-build.yml원하는 트리거 패턴에 따라 리포지토리에 추가하세요. 아래의 세 가지 트리거 패턴 중 하나를 선택하세요.
비밀 섹션에 들어갈 내용
비밀 섹션참고로, gh secret set -f 이러한 리포지토리 비밀 (워크플로우 YAML은 정확한 이름으로 참조합니다):
| 플랫폼 | 생성된 비밀 |
|---|---|
| iOS | BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID |
| 안드로이드 | ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON |
| (수동으로 추가됨) | CAPGO_TOKEN |
다음 예시들은 모두 필요 없는 정보를 기억하지 않아도 됩니다.
워크플로우 예시
워크플로우 예시 제목다음 세 가지 예시는 가장 일반적인 패턴을 다룹니다. 모두 동일한 형태를 사용합니다: 리포지토리를 체크아웃하고, 의존성을 설치하고, 웹 자산을 빌드하고, 네이티브로 동기화하고, Capgo 빌드에 인증 정보를 환경 변수로 전달합니다.
1. 수동 트리거
1. 수동 트리거 제목수동으로 빌드를 트리거하는 사람에게 누구나 쓰기 권한이 있는 경우 Actions GitHub의 탭에서 플랫폼 드롭다운을 사용하세요. 이 기능은 임시 테스트 빌드나 즉시 릴리스를 시작하는 데 유용합니다.
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 }}대체 com.example.app 앱 ID와 대체하세요. 커밋한 후, Actions → Capgo 빌드(수동) → 워크플로우 실행 으로 이동하세요.
2. 태그에 따라 릴리스
태그에 따라 릴리스버전 태그와 같은 것을 푸시할 때, 이 두 플랫폼 모두 병렬로 빌드하고 배포합니다. 이 설정은 가장 일반적인 프로덕션 설정입니다. v1.4.0__CAPGO_KEEP_0__ git tag v1.4.0 && git push --tags release 명령어로 변합니다.
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 releaseiOS와 Android를 별도의 실행자에서 병렬로 실행합니다. 설정 fail-fast: false iOS 빌드가 실패해도 Android 빌드가 중단되지 않으며, 그 반대도 마찬가지입니다. — 한 플랫폼이 임시 서명 문제를 겪고 있을 때 유용합니다.
3. 푸시 메인에 빌드 디버그
3. 푸시 메인으로 디버그 빌드푸시 메인에 대한 디버그 안드로이드 빌드를 생성하여 원래 빌드 회귀를 빠르게 발견합니다. main. 빌드가 저렴하고 빠른 feedback를 제공하며 Play Store 업로드를 생략하여 단순한 smoke test로 유지할 수 있습니다.
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필터는 문서 변경만이 아닌 workflow가 실행되지 않도록 합니다. paths Play Store 제출을 생략 (필요하지 않음) 하며, 결과 APK의 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 합니다. --no-playstore-upload 공통 패턴 PLAY_CONFIG_JSON 공통 패턴 --output-upload 필터는 문서 변경만이 아닌 workflow가 실행되지 않도록 합니다.
Play Store 제출을 생략 (필요하지 않음) 하며, 결과 APK의 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 합니다.
공통 패턴Play Store / 테스트 플라이트 업로드를 건너뛰세요
Play Store / 테스트 플라이트 업로드를 건너뛰는 섹션테스트 빌드의 경우 스토어 제출을 건너뛰세요: 안드로이드는 --no-playstore-uploadiOS의 경우 ad-hoc 모드에서 빌드합니다 (App Store로 제출되지 않습니다). 이에 --ios-distribution ad_hoc 을 결합하여 바이너리의 시간 제한된 다운로드 URL을 얻을 수 있습니다. --output-upload 스토어 릴리즈를 검토하기 위해 제출하세요
스토어 릴리즈를 검토하기 위해 제출하는 섹션
기본적으로 릴리즈 빌드는 서명된 아티팩트를 업로드하고 스토어 액션의 최종 결과를 사용자에게 맡깁니다. CI 릴리즈가 스토어 검토 흐름으로 직접 이동해야 하는 경우서비스 계정을 사용하세요. --submit-to-store-review.
explicit track이 없으면 PLAY_CONFIG_JSON service account이란 무엇입니까? service account이란 무엇입니까? --submit-to-store-review 기본적으로 프로덕션 트랙으로 설정됩니다. release_status: completed. 호출 사이트에서 트랙을 명시하는 것을 추천합니다. --android-track (또는 PLAY_STORE_TRACK), 그리고 상태를 오버라이드하려면 --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 키 경로를 사용하여 App Store 리뷰에 제출할 처리된 TestFlight 빌드를 제출합니다. 이는 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를 디스크에 영구적으로 저장하기 위해 빌드가 성공했을 때 빌드 아티팩트 URL 및 QR code를 디스크에 저장하고, 이후 단계에서 다시 읽어오기 위해 build last-output로그 스크래핑, 정규 표현식 없이.
- 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) and a PNG QR code alongside at /tmp/build.json.qr.png. build last-output writes a JSON record (with
--field outputUrl다운로드 URL만 출력합니다 (줄바꿈-종료; 안전한)URL=$(...)).--field qrCodePngPathPNG 경로를 출력하여 PR 첨부물로 업로드할 수 있습니다.--qr렌더링된 ASCII QR 코드를 출력합니다 — PR 댓글에 내장된 스캔 가능성을 위해 Markdown code 구획 안에 넣어주세요.
기본적으로 각 릴리즈 빌드는 빌드 번호를 증가시킵니다. Git 태그와 같은 값을 제어하는 데 사용할 수 있습니다. (예: 빌드 번호를 증가시키지 않도록 하려면)
클립보드에 복사Skip build number bumping --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 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 | 업로드하지 않도록 기본적으로 설정되어야 합니다. build init 프로비저닝 맵이 Xcode가 서명하는 다른 번들 ID를 참조하고 있습니다. 다시 실행하여 프로파일을 갱신한 후 다시 내보내세요. 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 레코드를 기록한 쪽의 __CAPGO_KEEP_0__ 버전보다 더 오래된 빌드러너가 사용되고 있습니다. 프로듀서와 리더를 동일한 명시적 버전으로 고정하세요 (예를 들어. Unsupported record schemaVersion | The 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, 이건 플랫폼 간에 드리프트가 발생할 수 있으므로 사용하지 마세요. |
For platform-specific build failures, see the Troubleshooting guide .
다음 단계
다음 단계 섹션
자동 OTA 또는 Native
브랜치 CI (live update 업로드와 Capgo 빌드 사이)
CI UI에서 트리거
Capgo 빌드를 액션 탭에서 수동으로 실행
빌드 웹 훅
관리자 대시보드 HTTP 호출에서 동일한 워크플로우를 시작
인증 정보 설정
iOS 및 Android 인증 정보를 base64 시크릿으로 준비하는 데 필요한 모든 참조
설정 옵션
모든 CLI 플래그 및 환경 변수를 사용하여 빌드를 최적화합니다.