본문 바로가기
Capgo - Capacitor 앱 빌드, 배포 및 업데이트 Capgo

설정 옵션

모든 Cloud Build 설정 옵션에 대한 완전한 레퍼런스입니다. 이 페이지를 사용하여 빌드 설정에 해당하는 CLI 플래그, 환경 변수 또는 자격 증명 키를 찾을 수 있습니다.

설정 우선순위

“Configuration Precedence” 섹션

모든 빌드 옵션은 여러 방식으로 설정할 수 있습니다. 동일한 옵션이 여러 위치에 설정된 경우, 우선순위가 높은 소스가 적용됩니다:

예시: 저장된 자격 증명에 SKIP_BUILD_NUMBER_BUMP=true 이 있지만 --no-skip-build-number-bump CLI에 CLI 플래그를 전달하면, CLI 플래그가 우선 적용되어 빌드 번호가 자동 증가됩니다.

iOS 옵션

“iOS 옵션” 섹션

Code 서명

“Code Signing” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--build-certificate-base64 <cert>BUILD_CERTIFICATE_BASE64BUILD_CERTIFICATE_BASE64—Base64 인코딩됨 .p12 배포 인증서
--ios-provisioning-profile <map>CAPGO_IOS_PROVISIONING_MAPCAPGO_IOS_PROVISIONING_MAP—프로비저닝 프로필을 다음과 같이 path 또는 bundleId=path 매핑합니다. 멀티 타겟 앱(앱 + 익스텐션)의 경우 반복 가능하며, 프로필 이름은 자동으로 추출됩니다.
--p12-password <password>P12_PASSWORDP12_PASSWORD—인증서 비밀번호 .p12 (인증서에 비밀번호가 없으면 생략)

App Store Connect 인증

“App Store Connect 인증” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--apple-key-id <id>APPLE_KEY_IDAPPLE_KEY_ID—App Store Connect API Key ID
--apple-issuer-id <id>APPLE_ISSUER_IDAPPLE_ISSUER_ID—App Store Connect Issuer ID (UUID)
--apple-key-content <content>APPLE_KEY_CONTENTAPPLE_KEY_CONTENT—Base64로 인코딩된 App Store Connect API 키 (.p8 파일)
--app-store-connect-team-id <id>APP_STORE_CONNECT_TEAM_IDAPP_STORE_CONNECT_TEAM_ID—App Store Connect 팀 ID
“앱 전용 비밀번호 인증 (권장하지 않음)” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--apple-id <email>FASTLANE_USERFASTLANE_USER—앱 소유자 계정의 Apple ID 이메일
--apple-app-specific-password <password>FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORDFASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD—앱 전용 비밀번호 (xxxx-xxxx-xxxx-xxxx)는 다음에서 생성됩니다: appleid.apple.com
--apple-app-id <id>APPLE_APP_IDAPPLE_APP_ID—숫자 App Store Connect 앱 ID (예: 1234567890)

iOS 빌드 설정

“iOS 빌드 설정” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--ios-scheme <scheme>CAPGO_IOS_SCHEMECAPGO_IOS_SCHEMEApp빌드할 Xcode 스킴
--ios-target <target>CAPGO_IOS_TARGETCAPGO_IOS_TARGETApp빌드 설정을 읽을 Xcode target
--ios-distribution <mode>CAPGO_IOS_DISTRIBUTIONCAPGO_IOS_DISTRIBUTIONapp_store배포 모드: app_store 또는 ad_hoc
--xcode-version <version>CAPGO_IOS_XCODE_VERSIONCAPGO_IOS_XCODE_VERSION모두예: 이 Xcode 버전으로 빌드 26, 26.0.1 또는 27. 메이저 버전만 지정하면 마이너 버전은 모두 허용됩니다. 일치하는 버전이 없으면 빌드가 즉시 실패하며 사용 가능한 버전 목록을 표시합니다.

Xcode 27

“Xcode 27” 섹션

Xcode 27 (iOS 27 SDK)로 빌드 --xcode-version 27:

터미널 창
npx @capgo/cli@latest build request --platform ios --xcode-version 27

iOS 27 SDK로 빌드된 앱은 UIScene 라이프사이클을 채택해야 합니다. 그렇지 않으면 UIApplicationSceneManifest 에서 Info.plist 및 scene delegate가 없으면 iOS 27에서 앱이 시작 시 중단됩니다. Capgo는 빌드 시작 전에 이러한 빌드를 차단합니다(프리스캔 체크 ios/plist-scene-lifecycle-xcode27). 추가하거나 SceneDelegate 및 UIApplicationSceneManifest 대상 ios/App/App/Info.plist, 또는 --xcode-version 26 까지 빌드를 계속하세요. Apple의 scene 라이프사이클 가이드.

CocoaPods 지원 종료 (2026년 12월)

“CocoaPods 지원 종료 (2026년 12월)” 섹션

Capgo Build는 2026년 12월부터 CocoaPods를 사용하는 iOS 프로젝트의 빌드를 중단합니다. 그 전에 프로젝트를 Swift Package Manager로 마이그레이션하세요: 참고 Capacitor SPM 가이드. 그 전까지는 CocoaPods 빌드가 계속 작동합니다. CLI은 경고를 표시하고, Capgo은 조직 관리자에게 리마인더 이메일을 보냅니다.

Android 옵션

“Android Options” 섹션

Keystore 서명

“Keystore Signing” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--android-keystore-file <keystore>ANDROID_KEYSTORE_FILEANDROID_KEYSTORE_FILE—Base64 인코딩된 keystore 파일 (.keystore 또는 .jks)
--keystore-key-alias <alias>KEYSTORE_KEY_ALIASKEYSTORE_KEY_ALIASkey0Keystore 키 별칭
--keystore-key-password <password>KEYSTORE_KEY_PASSWORDKEYSTORE_KEY_PASSWORD—Keystore 키 비밀번호 (설정하지 않으면 스토어 비밀번호 사용)
--keystore-store-password <password>KEYSTORE_STORE_PASSWORDKEYSTORE_STORE_PASSWORD—Keystore 저장소 비밀번호

Google Play 설정

“Google Play 구성” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--play-config-json <json>PLAY_CONFIG_JSONPLAY_CONFIG_JSON—Base64로 인코딩된 Google Play 서비스 계정 JSON 키
--android-track <track>PLAY_STORE_TRACKPLAY_STORE_TRACKinternal (또는 production 포함 --submit-to-store-review)Google Play 출시 트랙 (internal, alpha, beta, production). CI 환경 / CLI에서 빌드 러너로 전달됨.
--android-release-status <status>PLAY_STORE_RELEASE_STATUSPLAY_STORE_RELEASE_STATUSdraft (또는 completed 포함 --submit-to-store-review)선택한 트랙의 출시 상태 (draft, completed, inProgress, halted). 명시된 값은 --submit-to-store-review 기본값을 덮어씁니다.

Android 빌드 설정

“Android Build Settings” 섹션
CLI 플래그기본값설명
--android-flavor <flavor>—빌드할 Product flavor (예: production). 필수 프로젝트에 여러 flavor가 정의된 경우.
--android-track <track>internal이 업로드에 사용할 Google Play 트랙. --submit-to-store-review 트랙이 설정되지 않은 경우 Capgo의 기본값은 production.
--android-release-status <status>draftGoogle Play 릴리스 상태. --submit-to-store-review 상태가 설정되지 않은 경우 Capgo의 기본값은 completed.
--in-app-update-priority <0–5>—이 릴리스의 Google Play 인앱 업데이트 우선순위 (높을수록 긴급).
--no-playstore-upload—빌드 및 서명만 하고 Play Store 업로드는 건너뜀 (필요: --output-upload).

빌드 제어 옵션

“Build Control Options” 섹션

이 옵션은 iOS와 Android build 모두에 적용됩니다.

Build 모드

“Build 모드” 섹션
CLI 플래그기본값설명
--platform <platform>—필수 항목입니다. ios 또는 android
--build-mode <mode>releasedebug 또는 release
--path <path>.프로젝트 디렉토리
--verbosefalse상세 build 로그 활성화
--ai-analyticsfalse빌드 실패 시 Capgo AI로 로그를 보내 진단합니다 — 보기 AI 빌드 진단

빌드 번호 제어

“Build Number Control” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--skip-build-number-bumpSKIP_BUILD_NUMBER_BUMPSKIP_BUILD_NUMBER_BUMPfalse빌드 번호/버전 code 자동 증가 건너뛰기
--no-skip-build-number-bump———자동 증가 명시적으로 다시 활성화(저장된 자격 증명 무시)

기본적으로 Capgo Cloud Build는 빌드 번호를 자동으로 증가시킵니다:

  • iOS: App Store Connect에서 최신 빌드 번호를 가져와 1을 더합니다.
  • Android: 최대 fetch 횟수 versionCode 1을 더합니다.

시기 --skip-build-number-bump 설정되어 있으면 빌드는 프로젝트 파일에 이미 있는 버전을 그대로 사용합니다(Xcode 프로젝트 또는 build.gradle).

결과물 업로드

“출력 업로드” 섹션
CLI 플래그환경 변수자격 증명 키기본값설명
--output-uploadBUILD_OUTPUT_UPLOAD_ENABLEDBUILD_OUTPUT_UPLOAD_ENABLEDfalse빌드 결과물(IPA/APK/AAB)을 Capgo 스토리지에 업로드합니다. 환경 변수로 설정할 때는 다음을 사용하세요 BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-uploadBUILD_OUTPUT_UPLOAD_ENABLED——결과물 업로드를 비활성화합니다. 환경 변수로 설정할 때는 다음을 사용하세요 BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>BUILD_OUTPUT_RETENTION_SECONDSBUILD_OUTPUT_RETENTION_SECONDS1h다운로드 링크 활성 유지 기간
--output-record <path>———빌드가 성공하면 JSON 레코드(job ID, status, download URL, QR code)를 다음 위치에 기록합니다: <path> — 다음 명령어로 다시 읽어옵니다: build last-output.

보관 형식: 사람이 읽기 쉬운 기간을 사용하세요. 예: 1h, 6h, 2d, 7d. 최소 1시간, 최대 7일입니다. 환경 변수로 설정할 때는 초 단위를 사용하세요(예: 3600 1시간).

빌드 캐시

“Build cache” 섹션

Capgo는 컴파일된 네이티브 아티팩트(CocoaPods, Gradle 및 관련 빌드 결과물)를 저장하여 앱별로 반복 빌드가 더 빨리 시작됩니다. Build cache는 기본적으로 활성화되어 있습니다. 각 앱마다 적용됩니다.

CLI 플래그API 필드기본값설명
--no-cachecache_enabled: false캐시 사용이 빌드에서 캐시 비활성화: 복원 건너뛰기 및 새 항목을 저장하지 마세요
--cache-key <value>cache_key(생략)캐시를 분할하세요 (예: prod, staging). 앱당 하나의 공용 캐시를 사용하려면 생략하세요

CLI 대응 항목: build request 는 다음을 허용합니다: --no-cache 및 --cache-key.

CLI 예시:

터미널 창
# Default: restore/save the shared per-app cache
bunx @capgo/cli@latest build request com.example.app --platform android


# Separate caches per environment
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod


bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging


# One-off clean build (no restore, no save)
bunx @capgo/cli@latest build request com.example.app --platform ios --no-cache

API / Webhook 페이로드 (Capgo Build를 직접 호출하는 경우):

{
  "platform": "android",
  "cache_key": "prod"
}

생략 cache_key 공용 일반 캐시에 대해. 환경별로 분할하려면 cache_key 로 설정하세요. 단일 요청에 대해 캐시를 비활성화하려면 "cache_enabled": false 로 설정하세요 (와 동일) --no-cache).

빌드가 성공적으로 보이지만 아티팩트가 잘못되었거나, RC와 프로덕션 전환 후 Android AAB가 누락된 경우 전용 캐시 키나 일회용 --no-cache build. 참고 문제 해결: 잘못된 캐시 복구.

인증

“Authentication” 섹션
CLI 플래그환경 변수기본값설명
-a, --apikey <key>CAPGO_TOKEN—인증을 위한 Capgo API 키
--supa-host <host>——커스텀 Supabase 호스트 (셀프 호스팅 전용)
--supa-anon <key>——커스텀 Supabase anon key (셀프 호스팅 전용)

환경 변수 빠른 참조

“환경 변수 빠른 참조” 섹션

CI/CD 파이프라인에 바로 복사해 붙여넣을 수 있습니다. 모든 변수는 선택 사항이므로 필요한 것만 설정하세요.

iOS

“iOS” 섹션
터미널 창
# Code signing (required for iOS builds)
BUILD_CERTIFICATE_BASE64="<base64-encoded .p12>"
CAPGO_IOS_PROVISIONING_MAP="<provisioning map generated by the CLI>"
P12_PASSWORD="<certificate password>"


# App Store Connect (required for store submission)
APPLE_KEY_ID="ABC1234567"
APPLE_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
APPLE_KEY_CONTENT="<base64-encoded .p8 key>"
APP_STORE_CONNECT_TEAM_ID="TEAM123456"


# Alternative to the App Store Connect API key above: Apple ID + app-specific
# password (e.g. when migrating from Ionic Appflow). All three are required.
# FASTLANE_USER="apple-id@example.com"
# FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
# APPLE_APP_ID="1234567890"


# Optional iOS settings
CAPGO_IOS_SCHEME="App"
CAPGO_IOS_TARGET="App"
CAPGO_IOS_XCODE_VERSION="27"

Android

“Android” 섹션
터미널 창
# Keystore signing (required for Android builds)
ANDROID_KEYSTORE_FILE="<base64-encoded .keystore>"
KEYSTORE_KEY_ALIAS="my-key-alias"
KEYSTORE_KEY_PASSWORD="<key password>"
KEYSTORE_STORE_PASSWORD="<store password>"


# Google Play (required for store submission)
PLAY_CONFIG_JSON="<base64-encoded service account JSON>"


# Optional Android settings
PLAY_STORE_TRACK="internal"
PLAY_STORE_RELEASE_STATUS="draft"

빌드 제어

“빌드 제어” 섹션
터미널 창
# Build behavior
SKIP_BUILD_NUMBER_BUMP="true"          # Skip auto-increment
BUILD_OUTPUT_UPLOAD_ENABLED="true"     # Upload IPA/APK/AAB
BUILD_OUTPUT_RETENTION_SECONDS="3600"  # 1 hour download link


# Authentication
CAPGO_TOKEN="your-api-key"

Credential 저장

“Credential 저장” 섹션

로컬에 Credential 저장하기

“로컬에 Credential 저장하기” 섹션

매번 플래그나 환경 변수를 전달하는 대신, Credential을 한 번만 저장하세요:

터미널 창
# Save iOS credentials
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./dist_cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --p12-password "cert-password" \
  --apple-key ./AuthKey.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --apple-team-id TEAM123456


# Save Android credentials
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias my-key \
  --keystore-key-password "key-pass" \
  --keystore-store-password "store-pass" \
  --play-config ./play-service-account.json

저장 위치

“저장 위치” 섹션
플래그위치사용 사례
(기본값)~/.capgo-credentials/credentials.jsonGlobal — 로컬 머신의 모든 프로젝트에서 공유
--local.capgo-credentials.json 프로젝트 루트에프로젝트별 — 둘 다 있으면 Global 설정을 덮어씀

인증 정보는 다음을 키로 사용합니다 앱 ID (예: com.example.myapp), 따라서 하나의 인증 정보 파일로 여러 앱의 설정을 충돌 없이 저장할 수 있습니다. 각 앱의 인증 정보는 플랫폼별로 다시 나뉩니다 (ios / android).

저장된 자격 증명 관리

“저장된 자격 증명 관리” 섹션
터미널 창
# List saved credentials
bunx @capgo/cli@latest build credentials list


# Update a specific option without re-entering everything
bunx @capgo/cli@latest build credentials update --skip-build-number-bump


# Clear saved credentials
bunx @capgo/cli@latest build credentials clear --platform ios

예시

“예시” 섹션

GitHub 작업

“GitHub Actions” 섹션
name: Build and Submit
on:
  push:
    branches: [main]


jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx cap sync ios
      - run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          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 }}


  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx cap sync android
      - run: bunx @capgo/cli@latest build request --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

CLI 플래그 직접 사용하기

“CLI 플래그 직접 사용하기” 섹션
터미널 창
# Build iOS with all options inline
bunx @capgo/cli@latest build request \
  --platform ios \
  --build-mode release \
  --skip-build-number-bump \
  --output-retention 6h \
  --apikey YOUR_API_KEY


# Build Android, skip version bump, no output upload
bunx @capgo/cli@latest build request \
  --platform android \
  --skip-build-number-bump \
  --no-output-upload \
  --apikey YOUR_API_KEY

혼합 구성

“혼합 구성” 섹션

저장된 인증 정보와 CLI 오버라이드를 함께 사용하세요:

터미널 창
# Save base credentials once
bunx @capgo/cli@latest build credentials save --platform ios \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --output-upload


# Override specific options per-build
bunx @capgo/cli@latest build request --platform ios \
  --skip-build-number-bump \
  --output-retention 2d

저장된 인증 정보는 서명 세부 정보를 제공하며, CLI 플래그는 이번 실행에 한해 빌드 동작을 오버라이드합니다.