GitHub 액션

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

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

받는물

손쉽게 릴리즈

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

설치하지 않아도 됩니다.

__CAPGO_KEEP_0__에서 Windows 또는 Linux를 사용하는 기여자들은 iOS 빌드를 트리거할 수 있습니다. Xcode, 배포 프로비전 문제, 공유 서명 인증서가 노트북에 떠다니는 문제가 없습니다.

__CAPGO_KEEP_0__

GitHub

__CAPGO_KEEP_0__

Capgo Capgo API key
Capgobunx @capgo/cli@latest app add __CAPGO_KEEP_0__
지역에서 구성된 빌드 자격 증명 bunx @capgo/cli@latest build init — 참조 인증 관리 위치 워크숍을 위한
지역 빌드 성공 (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI에서 첫 번째 빌드를 디버깅하는 것은 CI의 장소가 아닙니다
The GitHub CLI (gh) 설치 및 인증 (gh auth login)

설정

The Capgo CLI can export your local credentials as a ready-to-use .env __CAPGO_KEEP_0__ __CAPGO_KEEP_1__은 로컬 자격 증명을 준비된 상태로 내보낼 수 있습니다. gh secret set -f이것과 함께

Add your Capgo API key as a repository secret

API __CAPGO_KEEP_1__ 키를 저장소 비밀로 추가하세요
__CAPGO_KEEP_0__ 키는 앱당 자격 증명 저장소에 포함되지 않으므로, 한 번만 수동으로 추가하세요:
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
클립보드 복사 Capgo 대시보드에서 키를 생성하세요 GitHub Actions을 사용하여 업로드 권한이 있는 사용자 또는 높은 권한이 있는 사용자입니다.
인증 정보를 파일로 내보내세요. .env 파일

인터랙티브 인증 관리자를 실행하세요:
터미널 창
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
TUI에서 선택하세요: .env로 내보내기. The CLI는 .env.capgo.<appId> 현재 디렉토리에 mode 0600 (owner-readable only) — 예를 들어 .env.capgo.com.example.app. iOS와 Android가 모두 구성되면 두 플랫폼의 비밀은 동일한 파일 아래에 저장됩니다. # === IOS === 및 # === ANDROID === section headers. iOS와 Android env-var 이름은 겹치지 않기 때문에 combining them은 conflict-free입니다.

Pass --platform ios (또는 --platform android)을 사용하여 manager를 하나의 플랫폼으로 제한합니다. 이때 export는 각 플랫폼별 파일을 생성합니다. 예를 들어 iOS와 Android의 비밀은 서로 다른 저장소 또는 환경에서 관리될 수 있습니다. .env.capgo.com.example.app.ios공유된 config 키

A config toggle의 몇 가지 설정이 (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) 각 플랫폼 별로 저장될 수 있으며, 플랫폼 간에 분리되어 있을 수 있습니다. manager가 분리가 발견되면, 충돌하는 키를 출력하고, 명시적인 확인을 받은 후 파일 상단에 충돌 목록을 주석으로 포함합니다. Re-export if per-platform 값이 유지되어야 합니다. --platform if 필요할 때는 per-platform 값을 유지하기 위해 Re-export합니다.
파일을 __CAPGO_KEEP_0__ Actions secrets로 푸시하세요. .env file to GitHub Actions secrets

명령어는 dotenv 파일을 읽고, 각 줄에 따라 repository secret를 생성합니다. gh secret set -f 터미널 창 KEY=value 클립보드에 복사
그것만 — 모든 secret가 이제 __CAPGO_KEEP_0__에 있습니다. Verify with
```
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.
Git에 .env 파일을 커밋하지 마세요.
플레인텍스트로 된 서명 자료를 포함하고 있기 때문입니다. GitHub에 푸시한 후:
터미널 창
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
인증서버리얼을 다시 내보내기할 때마다 — 파일은 장기적으로 사용되는 아티팩트가 아니기 때문입니다.
워크플로우 파일을 생성하세요.

Add .github/workflows/capgo-build.yml 저장소에 추가하세요. 사용하고 싶은 트리거 패턴 중 하나를 선택하세요.

Secrets 섹션

이 섹션은 다음 저장소 비밀을 생성합니다 (워크플로우 YAML은 정확한 이름으로 참조합니다): gh secret set -f Section titled “What ends up in your secrets”

플랫폼	생성된 비밀
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_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
(수동으로 추가됨)	`CAPGO_TOKEN`

이것들을 모두 기억할 필요는 없습니다 — 아래의 워크플로우 예제들은 이미 모든 것을 참조하고 있습니다.

워크플로우 예제

다음 세 가지 예제는 가장 일반적인 패턴을 다룹니다. 모두 같은 형태를 사용합니다: 리포지토리를 체크 아웃하고, 의존성을 설치하고, 웹 자산을 빌드하고, 네이티브로 동기화하고, Capgo 빌드에 인증 정보를 환경 변수로 전달합니다.

1. 수동 트리거

누구든지 쓰기 권한이 있는 사람에게는 빌드를 트리거하는 것을 허용합니다. 작업 GitHub의 탭에 플랫폼 드롭다운이 있습니다. 유용한 것은 ad-hoc 테스트 빌드 또는 수요에 따라 릴리즈를 시작하는 것입니다.

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 release 명령어로 변합니다.

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

이 필터는 문서 전용 변경만으로 워크플로우가 실행되지 않도록 보장합니다. paths 플레이 스토어 제출을 생략할 필요가 없으며, 결과 APK의 다운로드 URL을 생성하여 테스트 장치에 설치할 수 있습니다. --no-playstore-upload 공통 패턴 PLAY_CONFIG_JSON 공통 패턴 --output-upload __CAPGO_KEEP_0__

__CAPGO_KEEP_1__

Play Store / TestFlight 업로드 생략

테스트 빌드의 경우 스토어 제출을 생략합니다: Android는 --no-playstore-uploadiOS의 경우 ad-hoc 모드에서 빌드합니다 (App Store로 제출하지 않습니다). --ios-distribution ad_hoc (App Store로 제출하지 않습니다). 이 두 가지를 combine하여 바이너리의 시간 제한된 다운로드 URL을 얻을 수 있습니다. --output-upload 스토어 리뷰 제출

스토어 리뷰 제출 섹션

Android는 --submit-to-store-review.

서비스 계정. PLAY_CONFIG_JSON explicit track이 없으면 __CAPGO_KEEP_0__ --submit-to-store-review 기본적으로는 프로덕션 트랙으로 설정됩니다. release_status: completed. 호출 사이트에서 트랙을 명시하는 것을 추천합니다. --android-track (또는 PLAY_STORE_TRACK), 그리고 상태를 오버라이드하려면 --android-release-status / PLAY_STORE_RELEASE_STATUS 필요한 경우:

- 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 \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

내부 완료 릴리스 대신 프로덕션 대신:

- name: Submit Android internal release
  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 \
      --android-track internal \
      --store-release-name "${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디스크에 저장된 QR 코드 code를 읽어오기 위해 /tmp/build.json.qr.png. build last-output QR 코드 __CAPGO_KEEP_0__를 읽어오기 위해

--field outputUrl URL만 출력합니다 (줄바꿈-종료; PR 첨부물로 올릴 수 있습니다) URL=$(...)).
--field qrCodePngPath PNG 경로를 출력하여 PR 첨부물로 올릴 수 있습니다.
--qr ASCII QR을 렌더링하여 PR 댓글에 code 구간에 넣어 inline 스캔 가능성을 높일 수 있습니다.

빌드 번호 증가를 생략하는 방법

복사 --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) 은 더 큰 프로젝트에 대해 캐싱하는 것이 가치가 있습니다.

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

문제 해결

비밀 키가 추가되지 않았거나, 작업이 키에 접근할 수 없는 경우 (환경/branch 보호를 확인하세요)	iOS / Android 인증 정보가 누락된 오류
`CAPGO_TOKEN is not set`	실행되지 않았거나, 다른 저장소에 대해 실행된 경우. 확인하려면
CI에서 실패하지만 로컬에서 작동합니다.	`gh secret set -f` __CAPGO_KEEP_0__ `gh secret list`
`cap sync` __CAPGO_KEEP_0__	A native plugin이 없거나 `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`또는 artifact를 생성하기 전에 실패했습니다. `outputUrl` 레코드에 저장될 것입니다. `null` 이것을 사용하기 전에 branch를 합니다. `[ -n "$URL" ]` 에러가 발생합니다.
`build last-output` 레코드를 작성한 쪽의 __CAPGO_KEEP_0__ 버전보다 더 오래된 빌드러너에 있습니다. 양쪽 모두 동일한 명시적 버전으로 고정하세요 (예를 들어. `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 …` 이것이 아니라, 빌드러너가 float하고 job 간에 drift할 수 있기 때문에. `@latest`, which floats and can drift between jobs

For platform-specific build failures, see the Troubleshooting guide.

다음 단계

Auto OTA or Native Branch CI between live update upload and Capgo Build.

CI UI에서 트리거 Capgo Build를 Actions 탭에서 수동으로 실행

Build Webhooks 관리자 대시보드 HTTP 호출에서 동일한 워크플로우를 시작

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

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