손쉽게 릴리즈
Git에서 릴리즈 태그를 지정하면 TestFlight 및 Play Store로 자동으로 서명된 iOS 및 Android 바이너리가 제출됩니다.
이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.
iOS 및 Android 빌드를 직접 GitHub 저장소에서 자동화하세요. 단일 워크플로 파일과 몇 개의 저장소 비밀만 있으면, 팀의 누구도 Mac, Xcode, 또는 Android Studio가 설치되어 있지 않아도, 푸시, 태그, 또는 수동 트리거로 생성된 서명된, 저장소에 준비된 앱이 자동으로 생성됩니다.
손쉽게 릴리즈
Git에서 릴리즈 태그를 지정하면 TestFlight 및 Play Store로 자동으로 서명된 iOS 및 Android 바이너리가 제출됩니다.
지역 설정이 필요하지 않습니다
윈도우 또는 리눅스에서 작업하는 기여자들이 iOS 빌드를 트리거할 수 있습니다. Xcode, 프로비저닝 문제, 공유 서명 인증서가 노트북에 떠다니는 것과 같은 문제가 없습니다.
범위 지정된 비밀
인증 정보는 GitHub 저장소 비밀에 저장되어 있습니다. 저장소와 워크플로우 러너만이 볼 수 있습니다.
병렬 빌드
iOS와 Android를 동시에 빌드하세요. 매트릭스 작업을 사용하세요. 일반적인 릴리스는 10분 이내에 완료됩니다.
Capgo 계정에 활성 구독이 있는지 확인하고 Capgo __CAPGO_KEEP_1__ 키가 있는지 확인하세요.
bunx @capgo/cli@latest app add __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ keybunx @capgo/cli@latest build init if not 인증 관리 위자드 walkthrough를 위한bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI에서 첫 번째 빌드를 디버깅하는 것은 CI의 역할이 아닙니다.gh) 설치 및 인증 (gh auth login)Capgo CLI을 사용하여 로컬 인증서를 준비된 파일로 내보낼 수 있습니다. 이와 함께 .env , CI/CD 설정을 3개의 명령어로 변환합니다 — 수동 base64 인코딩, JSON 조작, 비밀 복사-붙여넣기-비밀-별개가 필요하지 않습니다. gh secret set -f__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키를 저장소 비밀로 추가하세요
Add your Capgo API key as a repository secret
The API key isn’t part of the per-app credential store, so add it once manually:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"__CAPGO_KEEP_0__ 대시보드에서 업로드 Capgo __CAPGO_KEEP_1__ __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ 이상의 권한이 필요합니다.
__CAPGO_KEEP_0__을 __CAPGO_KEEP_0__에 내보내세요. .env __CAPGO_KEEP_0__
__CAPGO_KEEP_0__를 실행하세요.
bunx @capgo/cli@latest build credentials manage --appId com.example.app__CAPGO_KEEP_0__에서 __CAPGO_KEEP_0__을 선택하세요. __CAPGO_KEEP_0__으로 내보내기CLI — 예를 들어, CLI에서 CLI을 CLI으로 쓰기 권한만 있습니다. .env.capgo.<appId> __CAPGO_KEEP_0__과 __CAPGO_KEEP_0__이 모두 설정되어 있는 경우, 두 플랫폼의 __CAPGO_KEEP_0__은 __CAPGO_KEEP_0__에 동일한 __CAPGO_KEEP_0__으로 저장됩니다. 0600 __CAPGO_KEEP_0__ writes .env.capgo.com.example.app__CAPGO_KEEP_0__에 __CAPGO_KEEP_0__으로 __CAPGO_KEEP_0__합니다. # === IOS === 그리고 섹션 헤더. iOS와 Android env-var 이름은 겹치지 않기 때문에 combining을 conflict-free로 하게 됩니다. # === ANDROID === 각 플랫폼별 파일이 필요합니까?
Push the .env 파일을 GitHub Actions secrets로 푸시하세요.
Capacitor gh secret set -f 명령어는 dotenv 파일을 읽고 한 줄 당 하나의 저장소 비밀을 생성합니다. KEY=value 터미널 창
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 | ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON |
| (added manually) | CAPGO_TOKEN |
이러한 workflow 예시들은 이미 모든 것을 참조하고 있기 때문에 memorize할 필요가 없습니다.
다음의 세 가지 예시는 가장 일반적인 패턴을 다룹니다. 모두 동일한 형태를 사용합니다: 저장소 확인, 의존성 설치, 웹 자산 빌드, 네이티브 동기화, 그리고 Capgo Build에 인증 정보를 환경 변수로 전달합니다.
write access 권한이 있는 모든 사용자가 Actions GitHub의 플랫폼 드롭다운을 사용하여 빌드를 트리거할 수 있습니다. ad-hoc 테스트 빌드나 필요시 릴리즈를 시작하는 데 유용합니다.
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와 함께. 커밋한 후에 작업 → Capgo 수동 빌드 → 워크플로우 실행 이를 트리거합니다.
모든 플랫폼을 동시에 빌드하고 배포합니다. 버전 태그를 푸시할 때 v1.4.0이것은 가장 일반적인 프로덕션 설정입니다. git tag v1.4.0 && git push --tags 이것이 릴리스 명령어가 됩니다.
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 빌드를 취소하지 않으며 (역방향도 마찬가지) — 한 플랫폼이 임시 서명 문제를 해결할 때 유용합니다.
디버그 빌드가 Native 빌드 회귀를 빠르게 잡아주기 때문에 Main으로 푸시할 때마다 디버그 Android 빌드를 생성합니다. main. 저렴한 비용, 빠른 feedback, Play Store 업로드를 생략하여 단순 테스트로 유지할 수 있습니다.
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-uploadThe paths 필터는 문서 변경만 있을 때 워크플로우가 실행되지 않도록 보장합니다. --no-playstore-upload Play Store 제출을 생략 (필요하지 않음)하고, 결과 APK의 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 합니다. PLAY_CONFIG_JSON 공통 패턴 --output-upload 제목: 공통 패턴
테스트 빌드의 경우 스토어 제출을 건너뛰십시오: 안드로이드는 --no-playstore-upload; iOS의 경우 ad-hoc 모드에서 빌드하여 --ios-distribution ad_hoc (이것은 앱 스토어에 제출되지 않습니다). 위의 두 가지를结合하여 --output-upload 바이너리 Binaries의 시간 제한된 다운로드 URL을 얻으십시오.
기본적으로 릴리즈 빌드는 서명된 아티팩트를 업로드하고 스토어의 마지막 액션을 사용자에게 맡깁니다. CI 릴리즈가 스토어 검토 흐름으로 직접 이동해야 하는 경우, --submit-to-store-review.
안드로이드는 PLAY_CONFIG_JSON 서비스 계정과 Google Play 릴리즈를 제출합니다. --store-release-name, --store-release-notesCI와 동일한 태그와 지역화된 변경 로그를 지닌 Play 릴리즈를 제출하고 싶은 경우, --store-release-notes-locale Copy to clipboard
- 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 \ --store-release-name "${GITHUB_REF_NAME}" \ --store-release-notes "Release ${GITHUB_REF_NAME}" \ --store-release-notes-locale "en-US=Release ${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 __CAPGO_KEEP_0__를 디스크에 저장하고, 이후 단계에서 다시 읽어보세요. --output-record <path> to persist the build artifact URL and QR code to disk when the build succeeds, then read it back in subsequent steps with 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)와 PNG QR code를 함께 생성합니다. /tmp/build.json.qr.png. build last-output 읽어옵니다.
--field outputUrl 다운로드 URL만 출력합니다 (줄바꿈 종결자; __CAPGO_KEEP_0__를 업로드할 수 있는 PR 첨부물로 안전합니다. URL=$(...)).--field qrCodePngPath PNG 경로를 출력하여 PR 첨부물로 업로드할 수 있습니다.--qr ASCII QR를 렌더링합니다 — PR 댓글에 내장된 스캔 가능성을 위해 Markdown code 구획에 넣어주세요.By default each release build increments the build number. To pin it to a value you control (for example, the Git tag), pass --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-bumpbun install is already fast enough that a JS-deps cache rarely pays off, but Capacitor’s native dependencies (CocoaPods, Gradle) are worth caching for larger projects:
- uses: actions/cache@v4 with: path: | ~/.bun/install/cache ios/App/Pods android/.gradle key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}| is already fast enough that a JS-deps cache rarely pays off, but __CAPGO_KEEP_0__’s native dependencies (CocoaPods, Gradle) are worth caching for larger projects: | 이미 JS 의존성 캐시가 빠르기 때문에 JS-deps 캐시가 거의 이익이 되지 않지만 __CAPGO_KEEP_0__의 원시 의존성 (CocoaPods, Gradle)은 더 큰 프로젝트에 대해 캐시하는 것이 가치가 있습니다: |
|---|---|
CAPGO_TOKEN is not set | __CAPGO_KEEP_0__이 설정되지 않았거나, 작업이 환경/branch 보호에 접근할 수 없습니다. |
| __CAPGO_KEEP_0__ iOS / Android 인증 정보가 누락되었습니다. | gh secret set -f __CAPGO_KEEP_0__이 실행되지 않았거나, 다른 저장소에 실행되었습니다. 확인하세요. gh secret list |
cap sync __CAPGO_KEEP_0__ CI에서 실패하지만 로컬에서 작동합니다. | __CAPGO_KEEP_0__이 native 플러그인이 없습니다. package.json__CAPGO_KEEP_0__이 설정되지 않았거나, __CAPGO_KEEP_0__을 忘れました. bun install __CAPGO_KEEP_0__ 이전에 cap sync |
| __CAPGO_KEEP_0__ 빌드가 성공했지만 App Store Connect에 앱이 나타나지 않습니다. | __CAPGO_KEEP_0__이 팀 ID가 잘못되거나, App Store Connect에 앱 레코드가 아직 존재하지 않습니다. 로컬에서 확인하세요. bunx @capgo/cli@latest build credentials manage |
| __CAPGO_KEEP_0__ 업로드 프로젝트 후에 빌드가 멈추었습니다. | __CAPGO_KEEP_0__ 프로젝트 아카이브가 비정상적으로 크다 — 환경을 확인하세요. node_modules __CAPGO_KEEP_0__이 업로드되지 않도록 (기본적으로 업로드되지 않도록) 확인하세요. |
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 있다. [ -n "$URL" ] 이것을 사용하기 전에 branch |
build last-output __CAPGO_KEEP_0__보다 오래된 __CAPGO_KEEP_0__에서 실행 중인 러너가 기록을 작성한 __CAPGO_KEEP_0__보다 오래된 __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플랫폼별 빌드 실패에 대한 자세한 내용은 |
문제 해결 가이드 다음 단계.