GitHub 액션

이 플러그인의 설치 단계 및 전체 마크다운 가이드가 포함된 설정 프롬프트 복사하기

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

받는 사람

손쉬운 릴리스

Git에서 릴리스 태그를 지정하면 TestFlight 및 Play Store로 자동으로 제출되는 signed iOS 및 Android 바이너리가 생성됩니다.

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

Windows 또는 Linux의 기여자도 iOS 빌드를 트리거할 수 있습니다. Xcode, 배포 문제, 공유 서명 인증서가 노트북에 떠다니는 문제가 없습니다.

범위 지정된 비밀

비밀은 GitHub 저장소 비밀에 저장되어 있습니다. 저장소와 워크플로 러너만 볼 수 있습니다. 쉽게 회전하고 쉽게 감사합니다.

병렬 빌드

iOS 및 Android을 동시에 빌드하세요. 일반적인 릴리스는 10분 이내에 완료됩니다.

설치 전 요구 사항

워크플로우를 설정하기 전에 다음을 확인하세요.

활성 구독 및 Capgo __CAPGO_KEEP_1__ 키가 있는 Capgo 계정 Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add 빌드 자격 증명이 로컬로 구성되어 있습니다.
자세한 내용은 Managing Credentials를 참조하세요. bunx @capgo/cli@latest build init 로컬 빌드가 성공적으로 완료되었습니다. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__
__CAPGO_KEEP_0__bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — CI는 첫 번째 빌드 디버깅을 위해 디버깅할 위치가 아닙니다.
The GitHub CLI (gh) 설치 및 인증 (gh auth login)

제목이 "설정"인 섹션

The Capgo CLI can export your local credentials as a ready-to-use .env file. Combined with gh secret set -f, 이 CI/CD 설정을 세 개의 명령으로 전환 — 수동 base64 인코딩, JSON 조작, 비밀번호를 복사-붙여넣기-비밀번호-비밀번호로.

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

API 키는 앱당 인증 정보 저장소에 포함되지 않으므로 수동으로 한 번만 추가하세요:
터미널 창
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
__CAPGO_KEEP_0__ 키를 __CAPGO_KEEP_0__ 대시보드에 생성하세요. Capgo dashboard 인증 정보를 파일로 내보세요. Generate the key in the __CAPGO_KEEP_0__ dashboard with upload permissions or higher. The __CAPGO_KEEP_0__ key isn’t part of the per-app credential store, so add it once manually:
Add your __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ key as a repository secret .env this turns the entire CI/CD setup into three commands — no manual base64 encoding, no JSON wrangling, no copy-paste-secret-by-secret.

Run the interactive credentials manager:
터미널 창
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
TUI에서 선택 .env로 내보내기 CLI은 .env.capgo.<appId> 현재 디렉토리에 (읽기 전용) 모드로 0600 (예를 들어,) .env.capgo.com.example.appiOS와 Android가 모두 설정되어 있을 때, 두 플랫폼의 비밀들이 # === IOS === 및 # === ANDROID === 구분된 이름을 가지는 환경 변수이므로, 그들을 합치는 것은 충돌이 없습니다.

Pass --platform ios (또는 --platform android)을 사용하여 매니저를 하나의 플랫폼으로 범위 지정합니다. 이때 내보낸 파일은 각 플랫폼별 파일과 같습니다. .env.capgo.com.example.app.iosiOS와 Android의 비밀은 다른 저장소 또는 환경에서 관리될 수 있으므로 유용합니다.

각 플랫폼별로 독립적으로 저장할 수 있는 몇 가지 구성 스위치(BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION)가 있습니다. 매니저가 이들 키가 다른 플랫폼에서 다른 값을 가지는 경우를 발견하면, 이들 키의 충돌을 출력하고 명시적인 확인을 받은 후 파일에 충돌 목록을 주석으로 추가합니다. 다시 내보내면 플랫폼별 값이 유지됩니다. --platform __CAPGO_KEEP_0__ Actions 비밀을 푸시할 때
__CAPGO_KEEP_0__ Actions 비밀을 푸시할 때 .env GitHub 액션 비밀을 푸시하세요.

명령어는 dotenv 파일을 읽고 한 줄당 하나의 저장소 비밀을 생성합니다. gh secret set -f 터미널 창 KEY=value 클립보드에 복사
그것이 다 — 이제 __CAPGO_KEEP_0__에 있는 모든 비밀 키가 __CAPGO_KEEP_0__에 있습니다. 확인하세요.
```
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.
터미널 창
It contains plaintext signing material. Once you’ve pushed it to GitHub:
인증서를 다시 내보낼 때마다 필요할 때마다 — 파일은 장기 보존된 항목이 아니기 때문에.
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
클립보드에 복사
워크플로우 파일을 생성하세요

추가 .github/workflows/capgo-build.yml repository에 추가하세요. 아래의 세 가지 트리거 패턴 중 하나를 선택하여 빌드를 트리거하십시오.

트리거 패턴

참조로 gh secret set -f 다음 repository 비밀을 생성합니다 (워크플로우 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`
(수동으로 추가)	`CAPGO_TOKEN`

이러한 workflow 예시들을 기억할 필요가 없습니다 — 아래의 workflow 예시들은 모두 참조합니다.

Workflow Examples

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

1. Manual Trigger

어떤 사람이라도 쓰기 권한이 있는 사용자는 __CAPGO_KEEP_0__의 'Actions' 탭에서 플랫폼 드롭다운을 사용하여 빌드를 트리거할 수 있습니다. ad-hoc 테스트 빌드나 필요에 따라 릴리즈를 시작하는 데 유용합니다. .__CAPGO_KEEP_0__/workflows/__CAPGO_KEEP_1__-build-manual.yml tab in GitHub with a platform dropdown. Useful for ad-hoc test builds or kicking off a release on demand.

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이것은 가장 일반적인 프로덕션 설정입니다. 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 release

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

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

메인 푸시 시 네이티브 빌드 회귀를 빠르게 잡아주는 디버그 안드로이드 빌드를 생성합니다. main실행 비용이 저렴하고 빠른 피드백을 제공하며, 플레이 스토어 업로드를 생략하여 단순한 스모크 테스트로 유지할 수 있습니다.

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

filter는 워크플로가 문서만 변경된 경우에 실행되지 않도록 하며, Play Store 제출을 생략 (필요하지 않음)하고, 결과물 APK에 대한 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 합니다. paths 공통 패턴 --no-playstore-upload Section titled “공통 패턴” PLAY_CONFIG_JSON Play Store / TestFlight 업로드 생략 --output-upload Section titled “Play Store / TestFlight 업로드 생략”

테스트 빌드의 경우, 스토어 제출을 생략합니다: Android는

The

skips Play Store submission (no --no-playstore-uploadneeded), and --ios-distribution ad_hoc produces a download URL for the resulting APK so you can install it on a test device. --output-upload 시간 제한된 바이너리 다운로드 URL을 얻기 위해.

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

Pass --output-record <path> 빌드가 성공했을 때 빌드 아티팩트 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)와 PNG QR 코드 code를 함께 기록합니다. /tmp/build.json.qr.png. build last-output 다시 읽어보세요:

--field outputUrl 다운로드 URL만 출력합니다 (줄바꿈 종결자; 다운로드에 안전합니다). URL=$(...)).
--field qrCodePngPath PNG 경로를 출력하여 PR 첨부 파일로 업로드할 수 있습니다.
--qr ASCII QR 코드를 렌더링하고 PR 댓글에 내장된 inline 스캔 가능성을 위해 code에 넣어주세요.

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

기본적으로 각 릴리스 빌드는 빌드 번호를 증가시킵니다. 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 보호를 확인하세요)
iOS / Android 인증 정보 오류	`gh secret set -f` 실행되지 않았거나, 또는 다른 저장소에 대해 실행되었습니다. `gh secret list`
`cap sync` CI 에서 실패하지만 로컬에서 작동합니다	네이티브 플러그인이 없거나, 또는 잊었습니다 `package.json`또는 `bun install` 앞서 `cap sync`
빌드가 성공했지만 App Store Connect에 앱이 나타나지 않습니다.	Wrong 팀 ID, 또는 App Store Connect에 앱 레코드가 아직 존재하지 않습니다. 로컬로 확인하세요. `bunx @capgo/cli@latest build credentials manage`
빌드가 "업로드 프로젝트" 후 "잠시 기다려 주세요"로 멈춥니다.	프로젝트 아카이브가 비정상적으로 크다 — 업로드되지 않는지 확인하세요. `node_modules` The provisioning map이 Xcode가 서명하는 다른 번들 ID를 가리키고 있습니다. 다시 실행하고 프로파일을 갱신한 후 다시 내보내세요.
`Provisioning profile doesn't match bundle ID`	로컬에서 인증 정보가 변경되었지만 CI가 실패합니다. `build init` Don’t forget to re-export and re-push: `build credentials manage`
Manager가 결합된 파일을 쓰기를 거부합니다.	플랫폼 간 공유 config 키가 다릅니다 — Manager가 경고하고 확인을 요청합니다. 하나를 덮어씌우려면 확인하세요, 아니면 플랫폼별로 다시 내보내세요. `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Wrong 팀 ID, 또는 App Store Connect에 앱 레코드가 아직 존재하지 않습니다. 로컬로 확인하세요.	프로젝트 아카이브가 업로드되지 않는지 확인하세요. `--platform ios` / `--platform android`
`build last-output` 빈 URL을 출력합니다.	빌드가 실패했습니다. `--output-upload`아티팩트를 생성하기 전에 실패했습니다. `outputUrl` 일부가 기록에 저장될 것입니다. `null` Branch on `[ -n "$URL" ]` 사용하기 전에
`build last-output` 에러가 발생합니다. `Unsupported record schemaVersion`	레코드를 작성한 버전보다 더 오래된 CLI 버전의 빌드러너가 사용되고 있습니다. 프로듀서와 리더를 동일한 명시적 버전 (예: `bunx @capgo/cli@7.104.0 …` 두 쪽 모두)으로 고정하는 것이 좋습니다. `@latest`빌드러너가 플랫폼에 따라 실패하는 경우

플랫폼별 빌드 실패에 대한 자세한 내용은 트러블 슈팅 가이드.

다음 단계

인증 정보 설정 iOS 및 Android 인증 정보를 base64 secret로 준비하는 데 필요한 모든 정보입니다.

iOS 빌드 인증서, 프로파일, 앱 스토어 제출에 대한 더 깊은 가이드입니다.

Android 빌드 Keystore 설정, Play Store 서비스 계정 및 맛을 위한 설정입니다.

설정 옵션 CLI