GitHub Actions

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 지시서를 복사하세요.

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

받는 이

손쉬운 릴리즈

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

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

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

범위별 비밀

GitHub에서 GitHub 저장소 비밀을 사용하여 인증 정보가 저장되며, 저장소와 워크플로우 러너만에게만 표시됩니다. 쉽게 회전하고 쉽게 감사합니다.

병렬 빌드

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

사전 요구 사항

__CAPGO_KEEP_0__ 계정과 활성 구독 및 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키가 있는

Capgo ( Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add __CAPGO_KEEP_0__
__CAPGO_KEEP_1__ bunx @capgo/cli@latest build init __CAPGO_KEEP_0__ 인증 정보 관리 위치 마법사 walkthrough
성공적인 로컬 빌드 (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI는 첫 번째 빌드에서 디버깅을 위해 사용하지 마세요
The GitHub CLI (gh) 설치 및 인증 (gh auth login)

설정

Capgo CLI은 로컬 인증 정보를 사용할 수 있는 파일로 내보낼 수 있습니다. 이와 함께, CI/CD 설정을 3개의 명령으로만 구성할 수 있습니다 — 수동 base64 인코딩, JSON 조작, 비밀번호 복사-붙여넣기 없이. .env __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 키를 저장소 비밀로 추가하세요. gh secret set -f__CAPGO_KEEP_0__ 키는 앱당 인증 정보 저장소에 포함되지 않으므로 수동으로 한 번만 추가하세요:

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:
__CAPGO_KEEP_0__ 키를 __CAPGO_KEEP_0__ 대시보드에서 생성하세요.
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
__CAPGO_KEEP_0__ Capgo dashboard with upload 권한이 __CAPGO_KEEP_0__ 이상인 경우.
__CAPGO_KEEP_0__을 파일에 내보내세요. .env 파일

CLI를 사용하여 자격 증명을 관리하세요.
터미널 창
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
TUI에서 선택 .env로 내보내기. CLI은 .env.capgo.<appId> 현재 디렉토리에 (읽기 전용으로) __CAPGO_KEEP_0__을 씁니다. 예를 들어, 0600 iOS와 Android가 모두 구성된 경우, 두 플랫폼의 비밀은 동일한 파일 아래에 저장됩니다. .env.capgo.com.example.app__CAPGO_KEEP_0__은 # === IOS === 그리고 # === ANDROID === iOS 및 Android env-var 이름은 분리되어 있으므로 combining을 conflict-free로 하게 됩니다.

Pass --platform ios (또는 --platform android)을 통해 매니저를 하나의 플랫폼으로 범위 지정합니다. 이때 export된 파일은 하나의 플랫폼에 맞는 파일이 됩니다. .env.capgo.com.example.app.iosiOS와 Android의 secret이 각각 다른 저장소나 환경에서 관리되는 경우 유용합니다.

몇몇 config toggle (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION)은 각 플랫폼별로 독립적으로 저장할 수 있으며, drift가 발생한 경우 manager는 conflict가 발생한 키를 출력하고 explicit 확인을 받은 후 conflict 목록을 파일의 첫 줄에 주석으로 추가합니다. 재-export합니다. --platform If you need to preserve per-platform values.
Push the .env 파일을 GitHub Actions secrets로 푸시하세요.

The gh secret set -f 명령어는 dotenv 파일을 읽고 한 줄당 하나의 레포지토리 비밀을 생성합니다. KEY=value Terminal 창
복사하기
```
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.
Once you’ve pushed it to __CAPGO_KEEP_0__:
GitHub로 푸시한 후에
터미널 창
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
__CAPGO_KEEP_0__
워크플로우 파일을 생성하세요

추가 .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 예시들을 기억할 필요가 없습니다. 아래의 workflow 예시들은 모든 workflow를 참조하고 있습니다.

Workflow Examples

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

1. Manual Trigger

write 권한이 있는 모든 사용자가 __CAPGO_KEEP_0__의 Actions 탭에서 플랫폼 드롭다운을 사용하여 빌드를 시작할 수 있습니다. ad-hoc 테스트 빌드나 필요에 따라 릴리즈를 시작하는 데 유용합니다. Actions 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 __CAPGO_KEEP_0__ ID를 넣으세요. 커밋한 후에 작업 → Capgo 수동 빌드 → 워크플로우 실행 이를 트리거하세요.

2. 태그에 릴리즈

태그와 같은 버전을 푸시할 때 두 플랫폼 모두 병렬로 빌드하고 배포합니다. v1.4.0이것은 가장 일반적인 프로덕션 설정 — git tag v1.4.0 && git push --tags __CAPGO_KEEP_0__/작업 흐름/__CAPGO_KEEP_1__-릴리즈 빌드.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으로 푸시할 때 디버그 빌드 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

The paths 필터는 문서 변경만으로 workflow가 실행되지 않도록 ensures합니다. --no-playstore-upload Play Store 제출을 생략 (필요하지 않음)하고, PLAY_CONFIG_JSON 결과 APK에 대한 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록 해줍니다. --output-upload 공통 패턴

제목: 공통 패턴

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

테스트 빌드의 경우 스토어 제출을 건너뛰십시오: Android는 --no-playstore-upload; iOS의 경우 ad-hoc 모드에서 빌드하여 --ios-distribution ad_hoc (이것은 App Store로 제출되지 않습니다). 위의 두 가지를结合하여 --output-upload 를 사용하여 바이너리의 시간 제한 다운로드 URL을 얻으십시오.

스토어 릴리즈를 검토 요청

기본적으로 릴리즈 빌드는 서명된 아티팩트를 업로드하고 스토어의 마지막 작업을 사용자에게 맡깁니다. CI 릴리즈가 스토어 검토 흐름으로 직접 이동할 수 있도록 하려면 --submit-to-store-review.

Android는 PLAY_CONFIG_JSON 서비스 계정과 함께 Google Play 릴리즈를 제출하고, 그 대신에 스토어에 제출하지 않습니다. --store-release-name, --store-release-notes를 추가하여, 선택적 --store-release-notes-locale entries를 사용하여 Play 릴리즈가 CI와 동일한 태그와 지역화된 변경 로그를 가지고 있도록 하십시오.

- 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를 읽어보세요.

성공 --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)과 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 구획 내에 넣으십시오.

Skip 빌드 번호 업데이트를 생략합니다.

기본적으로 각 릴리스 빌드는 빌드 번호를 증가시킵니다. 이를 특정 값 (예: Git 태그)에 고정하려면 __CAPGO_KEEP_0__를 통과하세요. --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 의존성 캐시가 빠르기 때문에 JS-deps 캐시가 자주 유용하지 않지만 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`	__CAPGO_KEEP_0__이 설정되지 않았거나, 작업이 환경/branch 보호에 접근할 수 없습니다.
iOS / Android 인증 정보가 누락된 오류	`gh secret set -f` __CAPGO_KEEP_0__이 실행되지 않았거나, 다른 저장소에 실행된 것입니다. __CAPGO_KEEP_1__으로 확인하세요. `gh secret list`
`cap sync` CI에서 실패하지만 로컬에서 작동합니다.	__CAPGO_KEEP_0__이 native 플러그인이 없습니다. `package.json`__CAPGO_KEEP_0__이 설정되지 않았거나, __CAPGO_KEEP_1__을 잊었을 수 있습니다. `bun install` __CAPGO_KEEP_0__ `cap sync`
__CAPGO_KEEP_0__이 성공적으로 빌드되었지만 App Store Connect에 앱이 나타나지 않습니다.	__CAPGO_KEEP_0__ ID가 잘못되거나, 앱 레코드가 App Store Connect에 아직 존재하지 않습니다. 로컬에서 __CAPGO_KEEP_1__으로 확인하세요. `bunx @capgo/cli@latest build credentials manage`
__CAPGO_KEEP_0__가 '업로드 프로젝트' 후에 멈추면서 빌드가 지연됩니다.	__CAPGO_KEEP_0__가 비정상적으로 크기인 경우 __CAPGO_KEEP_1__을 확인하세요. `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>`
관리자에서 결합된 파일을 쓰기를 거부합니다.	플랫폼 간에 공유된 config 키가 다르기 때문에 관리자는 경고하고 확인을 요청합니다. 하나를 덮어씌우려면 확인하거나 플랫폼별로 다시 내보내기하세요. `--platform ios` / `--platform android`
`build last-output` 빈 URL을 출력합니다.	빌드가 실패했습니다. `--output-upload`또는 빌드가 실패하기 전에 아티팩트를 생성하지 못했습니다. `outputUrl` 기록에 `null` Branch on `[ -n "$URL" ]` 사용하기 전에
`build last-output` 오류와 `Unsupported record schemaVersion`	실행자는 기록을 작성한 것보다 CLI가 더 오래된 상태입니다. 프로듀서와 리더를 동일한 명시적 버전 (예를 들어, "on both sides")에 고정하는 것이 좋습니다. `bunx @capgo/cli@7.104.0 …` , `@latest`플랫폼별 빌드 실패에 대한 자세한 내용은

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

다음 단계

iOS 및 Android 인증 정보를 base64 secret로 준비하는 데 대한 전체 참조 iOS 빌드

인증서, 프로파일, 앱 스토어 제출에 대한 더 깊은 가이드 protectedTokens

안드로이드 빌드 Keystore 설정, Play Store 서비스 계정 및 맛집 처리.

설정 옵션 모든 CLI 플래그 및 환경 변수를 빌드에 대한 세부 조정을 위해.