GitHub Actions

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

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

What You Get

Hands-off Releases

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

No Local Setup

윈도우 또는 리눅스에서 작업하는 기여자들이 iOS 빌드를 트리거할 수 있습니다. Xcode, 배포 설정, 공유 서명 인증서가 노트북에 떠다니는 문제가 없습니다.

Scoped Secrets

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

Parallel Builds

iOS 및 Android를 동시에 빌드할 수 있습니다. 일반적인 릴리스는 10분 이내에 완료됩니다.

Prerequisites

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

활성 구독과 Capgo __CAPGO_KEEP_1__ 키가 있는 Capgo 계정 Capgo API 키
앱이 Capgo (bunx @capgo/cli@latest app add 만약 그렇지 않다면
로 등록되어야 합니다. bunx @capgo/cli@latest build init 빌드 자격 증명을 로컬 컴퓨터에 구성했으며 — Managing Credentials
을 참조하세요.bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug로컬 빌드가 성공적으로 완료되었으며 (
The GitHub CLI (gh) __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ (gh auth login)

Setup

The Capgo CLI can export your local credentials as a ready-to-use .env , this turns the entire CI/CD setup into three commands — no manual base64 encoding, no JSON wrangling, no copy-paste-secret-by-secret. gh secret set -f설치 및 인증 (

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

API 키는 앱당 인증 정보 저장소의 일부가 아니므로 수동으로 한 번만 추가하세요:
터미널 창
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
__CAPGO_KEEP_0__ 대시보드에서 키를 생성하세요 Capgo 대시보드에서 키를 생성하세요 __CAPGO_KEEP_0__ 대시보드에서 키를 생성하세요 __CAPGO_KEEP_0__ 대시보드에서 키를 생성하세요 __CAPGO_KEEP_0__ 대시보드에서 키를 생성하세요
인증 정보를 파일로 내보세요 .env 인증 정보를 파일로 내보세요

인터랙티브 인증 정보 관리자를 실행하세요
터미널 창
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
TUI에서 선택하세요. .env로 내보내기CLI은 .env.capgo.<appId> 현재 디렉토리에 모드 0600 예를 들어, .env.capgo.com.example.app. iOS와 Android가 모두 설정되어 있을 때, 두 플랫폼의 비밀은 # === IOS === 및 # === ANDROID === 구분자입니다. iOS와 Android의 환경 변수 이름은 겹치지 않기 때문에 combining은 충돌이 없습니다.

Pass --platform ios (or --platform android)을 사용하여 매니저를 하나의 플랫폼으로 제한합니다. 이때 내보낸 파일은 플랫폼별 파일과 같습니다. .env.capgo.com.example.app.iosiOS와 Android의 비밀키가 다른 저장소 또는 환경에 존재할 때 유용합니다.

각 플랫폼별로 독립적으로 저장할 수 있는 config 토글(BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION)이 몇 개 있습니다. 매니저가 드리프트를 발견하면 충돌하는 키를 출력하고 명시적인 확인을 받은 후 파일에 충돌 목록을 주석으로 추가합니다. 다시 내보내면 --platform if 필요할 때 플랫폼별 값을 보존합니다.
__CAPGO_KEEP_0__ Actions secrets에 .env file to GitHub Actions secrets

The gh secret set -f 명령어는 dotenv 파일을 읽고 하나의 저장소 비밀을 생성합니다. KEY=value 줄:
터미널 창
```
gh secret set -f .env.capgo.com.example.app
```
그것이 다 — 이제 GitHub에 업로드한 모든 비밀을 확인하세요. gh secret list.
Don't commit the .env file
It contains plaintext signing material. Once you’ve pushed it to GitHub:
그것을 __CAPGO_KEEP_0__:에 푸시한 후:
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
클립보드에 복사
인증서버를 다시 로드할 때마다 다시 내보내세요 — 파일은 장기적으로 사용되지 않습니다.

등록 .github/workflows/capgo-build.yml 원하는 빌드 트리거 패턴을 선택하세요.

비밀을 포함하는 섹션

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

생성된 비밀	iOS
Android	`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_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
이러한 비밀을 모두 기억할 필요는 없습니다. 아래의 워크플로우 예제는 이미 모든 것을 참조하고 있습니다.	`CAPGO_TOKEN`

Add

워크플로우 예시

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

1. 수동 트리거

이 섹션에서는 쓰기 권한이 있는 모든 사용자가 __CAPGO_KEEP_0__의 "Actions" 탭에서 플랫폼 드롭다운을 사용하여 빌드를 트리거할 수 있습니다. 이 기능은 임의 테스트 빌드나 필요 시 릴리스를 트리거하는 데 유용합니다. __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 }}

Replace with your app ID. com.example.app Copy to clipboard. 액션 → Capgo Build (수동) → 워크플로우 실행 이를 트리거합니다.

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 브랜치 푸시 시 디버그 빌드

Main 브랜치 푸시 시 Native 빌드의 오류를 빠르게 발견할 수 있습니다. mainCheap to run, fast feedback, and you can skip Play Store upload to keep it purely a 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 filter는 워크플로가 문서 변경만으로 실행되지 않도록 보장합니다. --no-playstore-upload Play Store 제출을 생략합니다 (필요하지 않음) 및 PLAY_CONFIG_JSON 결과물 APK에 대한 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있도록합니다. --output-upload 공통 패턴

공통 패턴

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

둘 중 하나와 combine하여 바이너리의 시간 제한된 다운로드 URL을 얻을 수 있습니다. --no-playstore-upload__CAPGO_KEEP_0__ --ios-distribution ad_hoc __CAPGO_KEEP_0__ --output-upload __CAPGO_KEEP_0__

스토어 릴리스를 검토하기 위해 제출하세요

기본적으로 릴리스 빌드는 서명된 아티팩트를 업로드하고 최종 스토어 액션을 사용자에게 맡깁니다. CI 릴리스가 바로 스토어 검토 흐름으로 이동해야 하는 경우, --submit-to-store-review.

Android는 PLAY_CONFIG_JSON 서비스 계정과 Google Play 릴리스를 제출하는 대신에 비활성화합니다. --store-release-name, --store-release-notes와 선택적 --store-release-notes-locale 을 추가할 때 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 uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store 키 경로를 사용하여 App Store 리뷰에 제출된 처리된 테스트 플라이트 빌드를 제출합니다. --ios-testflight-groups 배포에 필요합니다.

- 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> 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만 출력합니다 (줄바꿈 종결자; 안전합니다. 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 이미 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`	비밀번호가 등록되지 않았거나, 작업이 환경/branch 보호에 접근할 수 없음 (환경/branch 보호 확인)
iOS / Android 인증 정보 오류	`gh secret set -f` CI에서 실패했지만 로컬에서 작동함. 확인하려면 `gh secret list`
`cap sync` 실패	원본 플러그인은 없습니다 `package.json`, 또는 잊었습니다 `bun install` 앞서 `cap sync`
빌드가 성공했지만 App Store Connect에 앱이 나타나지 않습니다	팀 ID가 잘못되거나, App Store Connect에 앱 레코드가 아직 존재하지 않습니다. 로컬로 확인하세요. `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" ]` 브랜치
`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 …` 레코드를 생성한 프로듀서와 읽는 사용자가 다른 버전을 사용하고 있습니다. 프로듀서와 리더를 동일한 명시적 버전으로 고정하세요 (예를 들어 `@latest`두 쪽 모두) 대신에, 버전이 변동하고 드리프트할 수 있습니다.

플랫폼별 빌드 실패에 대한 자세한 내용은 문제 해결 가이드.

다음 단계

인증 정보 설정 __CAPGO_KEEP_0__ 플래그 및 환경 변수의 모든 설정 옵션을 포함한 iOS 및 Android 인증 정보를 base64로 암호화하는 방법의 전체 참조.

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

Android 빌드 Keystore 설정, Play Store 서비스 계정 및 맛 종류 관리.

설정 옵션 CLI 플래그 및 환경 변수의 모든 설정 옵션을 포함한 빌드의 세부 설정.