GitHub Actions

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

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

받는 사람

손쉬운 릴리즈

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

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

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

범위 지정된 비밀

GitHub 저장소 비밀을 통해 GitHub에서 인증 정보가 살아있다. repo와 workflow runner만이 볼 수 있습니다. 쉽게 회전하고 쉽게 감사합니다.

Parallel Builds

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

Prerequisites

Before setting up the workflow, make sure you have:

Capgo 계정에 활성 구독이 있는지 확인하고 Capgo __CAPGO_KEEP_1__ 키가 있는지 확인하세요. Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add __CAPGO_KEEP_0__에서 앱을 등록하세요. (
if not) bunx @capgo/cli@latest build init __CAPGO_KEEP_0__ 빌드 인증 정보를 로컬에서 구성하세요. — see 인증 관리 위자드 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 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_0__ 대시보드에 업로드하세요. __CAPGO_KEEP_0__에 업로드하세요. __CAPGO_KEEP_0__ 또는 높은 권한이 필요합니다.
__CAPGO_KEEP_0__을 __CAPGO_KEEP_0__에 내보내세요. .env __CAPGO_KEEP_0__

__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을 기록합니다. .env.capgo.<appId> __CAPGO_KEEP_0__으로 __CAPGO_KEEP_0__을 기록합니다. (__CAPGO_KEEP_0__ 읽기 전용) — 예를 들어, 0600 __CAPGO_KEEP_0__이 __CAPGO_KEEP_0__과 __CAPGO_KEEP_0__이 모두 설정되어 있을 때, 두 플랫폼의 __CAPGO_KEEP_0__은 __CAPGO_KEEP_0__에 동일한 __CAPGO_KEEP_0__을 기록합니다. .env.capgo.com.example.app__CAPGO_KEEP_0__ # === IOS === 그리고 섹션 헤더. iOS와 Android env-var 이름은 겹치지 않기 때문에 combine하는 것은 conflict-free입니다. # === ANDROID === 각 플랫폼별 파일이 필요합니까?

(또는 --platform ios )을 사용하여 매니저를 하나의 플랫폼으로 범위 지정합니다. 이때 export하면 각 플랫폼별 파일이 생성됩니다. --platform androidiOS와 Android의 secret이 다른 저장소 또는 환경에서 관리되는 경우 유용합니다. .env.capgo.com.example.app.ios공유 config 키

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

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

추가 .github/workflows/capgo-build.yml 프로젝트에 추가하세요. 아래의 세 가지 트리거 패턴 중 하나를 선택하여 빌드를 트리거할 수 있습니다.

비밀을 저장하는 곳

이러한 레포지토리 비밀 (워크플로우 YAML은 정확한 이름으로 참조합니다): gh secret set -f 플랫폼

생성된 비밀	__CAPGO_KEEP_0__
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 Examples

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

1. Manual Trigger

__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 앱 ID와 함께. 커밋한 후에 작업 → 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. 메인 푸시 시 디버그 빌드

Section titled “3. Debug Build on Push to Main” 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-upload

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

제목 "공통 패턴"

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

테스트 빌드의 경우, 앱 스토어 제출을 생략합니다: 안드로이드는 --no-playstore-upload; iOS의 경우, ad-hoc 모드에서 빌드합니다 (이것은 앱 스토어에 제출되지 않습니다). --ios-distribution ad_hoc Capacitor와 --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만 출력합니다 (줄바꿈 종결자; CLI에서 안전합니다) URL=$(...)).
--field qrCodePngPath PNG 경로를 출력하여 PR 첨부물로 업로드할 수 있습니다.
--qr 렌더링된 ASCII QR을 출력합니다 — PR 댓글에 내장 스캔 가능성을 위해 Markdown 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 Capacitor의 네이티브 의존성(CocoaPods, Gradle)은 더 큰 프로젝트에 대해 캐싱하는 것이 가치가 있습니다. 그러나 JS 의존성 캐시는 이미 빠르기 때문에 자주 보상되지 않습니다.

- 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` __CAPGO_KEEP_0__가 실행되지 않았거나, 다른 저장소에 대해 실행된 경우. 확인하세요. `gh secret list`
`cap sync` CI에서 성공하지만 로컬에서만 작동합니다.	자연스럽게 플러그인은 없습니다. `package.json`, 또는 잊었을 수도 있습니다. `bun install` 전에 `cap sync`
빌드가 성공했지만 앱 스토어 연결에 나타나지 않습니다.	오류가 있는 팀 ID, 또는 앱 기록이 아직 앱 스토어 연결에 존재하지 않습니다. 로컬에서 "를 사용하여 확인하세요. `bunx @capgo/cli@latest build credentials manage`
업로드 후 "빌드가 멈추고 있습니다.	프로젝트 아카이브가 비정상적으로 크다 — 로컬에서 "를 확인하세요. `node_modules` 업로드되지 않는다는 것을 확인하세요 (기본적으로 업로드되지 않아야 함).
`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`아티팩트를 생성하기 전에 실패했습니다. `outputUrl` 될 것입니다. `null` 기록에 저장될 것입니다. `[ -n "$URL" ]` Branch on
`build last-output` 사용하기 전에 `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 …` 기록을 작성한 쪽의 버전보다 더 오래된 __CAPGO_KEEP_0__ 버전을 사용하는 실행자입니다. 프로듀서와 리더를 동일한 명시적 버전으로 고정하세요 (예를 들어, `@latest`__CAPGO_KEEP_0__

플랫폼에 따라 빌드가 실패하는 경우 문제 해결 가이드.

다음 단계

iOS 및 Android 인증서, 프로파일, 앱 스토어 제출을 위한 준비된 base64 비밀키를 위한 전체 참조. iOS 빌드

인증서, 프로파일, 앱 스토어 제출을 위한 더 깊은 가이드. Android 빌드

Keystore 설정, 플레이 스토어 서비스 계정, 맛을 다루는 방법. 설정 옵션

__CAPGO_KEEP_0__ 모든 CLI 플래그 및 환경 변수를 사용하여 빌드의 세부 설정을 조정합니다.