메뉴로 바로가기

GitHub Actions

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

손쉽게 릴리즈

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

지역 설정이 필요하지 않습니다

윈도우 또는 리눅스에서 작업하는 기여자들이 iOS 빌드를 트리거할 수 있습니다. Xcode, 프로비저닝 문제, 공유 서명 인증서가 노트북에 떠다니는 것과 같은 문제가 없습니다.

범위 지정된 비밀

인증 정보는 GitHub 저장소 비밀에 저장되어 있습니다. 저장소와 워크플로우 러너만이 볼 수 있습니다.

병렬 빌드

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

Capgo 계정에 활성 구독이 있는지 확인하고 Capgo __CAPGO_KEEP_1__ 키가 있는지 확인하세요.

  • A Capgo account with an active subscription and a Capgo API key
  • A Capgo account with an active subscription and abunx @capgo/cli@latest app add __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ key
  • Your app registered in __CAPGO_KEEP_0__ ( bunx @capgo/cli@latest build init if not 인증 관리 위자드 walkthrough를 위한
  • 성공적인 로컬 빌드 (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI에서 첫 번째 빌드를 디버깅하는 것은 CI의 역할이 아닙니다.
  • The GitHub CLI (gh) 설치 및 인증 (gh auth login)

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__

설정

Capgo CLI을 사용하여 로컬 인증서를 준비된 파일로 내보낼 수 있습니다. 이와 함께 .env , CI/CD 설정을 3개의 명령어로 변환합니다 — 수동 base64 인코딩, JSON 조작, 비밀 복사-붙여넣기-비밀-별개가 필요하지 않습니다. gh secret set -f__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키를 저장소 비밀로 추가하세요

  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__ 이상의 권한이 필요합니다.

  2. __CAPGO_KEEP_0__을 __CAPGO_KEEP_0__에 내보내세요. .env __CAPGO_KEEP_0__

    __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 === 각 플랫폼별 파일이 필요합니까?

  3. Push the .env 파일을 GitHub Actions secrets로 푸시하세요.

    Capacitor gh secret set -f 명령어는 dotenv 파일을 읽고 한 줄 당 하나의 저장소 비밀을 생성합니다. KEY=value 터미널 창

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

    That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.

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

    추가 .github/workflows/capgo-build.yml 저장소에 추가하세요. 세 가지 트리거 패턴 중 하나를 선택하여 빌드를 트리거하는 방법에 따라 빌드 트리거를 선택하세요.

비밀을 저장하는 곳

비밀을 저장하는 곳

참고로 gh secret set -f 이러한 저장소 비밀 (워크플로 YAML은 정확한 이름으로 참조합니다):

플랫폼생성된 비밀
iOSBUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
AndroidANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON
(added manually)CAPGO_TOKEN

이러한 workflow 예시들은 이미 모든 것을 참조하고 있기 때문에 memorize할 필요가 없습니다.

Workflow Examples

Workflow Examples 섹션

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

1. Manual Trigger

1. Manual Trigger 섹션

write access 권한이 있는 모든 사용자가 Actions GitHub의 플랫폼 드롭다운을 사용하여 빌드를 트리거할 수 있습니다. ad-hoc 테스트 빌드나 필요시 릴리즈를 시작하는 데 유용합니다.

/github/작업 흐름/capgo-수동 빌드.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 }}

바꾸기 com.example.app 앱 ID와 함께. 커밋한 후에 작업 → Capgo 수동 빌드 → 워크플로우 실행 이를 트리거합니다.

2. 태그에 릴리스

제목 '2. 태그에 릴리스'

모든 플랫폼을 동시에 빌드하고 배포합니다. 버전 태그를 푸시할 때 v1.4.0이것은 가장 일반적인 프로덕션 설정입니다. git tag v1.4.0 && git push --tags 이것이 릴리스 명령어가 됩니다.

/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. Main으로 푸시할 때 디버그 빌드

3. Main으로 푸시할 때 디버그 빌드

디버그 빌드가 Native 빌드 회귀를 빠르게 잡아주기 때문에 Main으로 푸시할 때마다 디버그 Android 빌드를 생성합니다. main. 저렴한 비용, 빠른 feedback, Play Store 업로드를 생략하여 단순 테스트로 유지할 수 있습니다.

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 제출을 생략 (필요하지 않음)하고, 결과 APK의 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 합니다. PLAY_CONFIG_JSON 공통 패턴 --output-upload 제목: 공통 패턴

Play Store / TestFlight 업로드 생략

제목: Play Store / TestFlight 업로드 생략

filter ensures the workflow doesn’t run on doc-only changes.

produces a download URL for the resulting APK so you can install it on a test device.

테스트 빌드의 경우 스토어 제출을 건너뛰십시오: 안드로이드는 --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 code를 읽어보세요.

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

성공 시 빌드 아티팩트 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-bump

Copy to clipboard

Cache dependencies

bun 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') }}

Cache 의존성

Copy to clipboard
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 IDXcode가 서명하는 다른 번들 ID를 가리키는 배포 프로비저닝 맵입니다. 다시 실행하여 build init 프로파일을 갱신하고 다시 내보내세요. build credentials manage
CI에서 실패하지만 로컬에서 인증 정보가 변경되었습니다.잊지 마세요. 다시 내보내고 다시 푸시하세요: bunx @capgo/cli@latest build credentials managegh 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 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플랫폼별 빌드 실패에 대한 자세한 내용은

문제 해결 가이드 다음 단계.