설정 옵션

Cloud Build 구성 옵션의 모든 완전한 참조입니다. 이 페이지를 사용하여 CLI 플래그, 환경 변수 또는 인증 키를 찾으십시오.

구성 순위

모든 빌드 옵션은 여러 가지 방법으로 설정할 수 있습니다. 동일한 옵션이 여러 곳에서 설정될 때, 우선순위가 높은 소스에서 우선순위가 낮은 소스를 이길 수 있습니다:

flowchart LR
    A["🔧 CLI Flag"] -->|overrides| B["🌍 Environment Variable"]
    B -->|overrides| C["📁 Local Credentials"]
    C -->|overrides| D["🏠 Global Credentials"]
    style A fill:#6366f1,color:#fff,stroke:#4f46e5
    style B fill:#8b5cf6,color:#fff,stroke:#7c3aed
    style C fill:#a78bfa,color:#fff,stroke:#8b5cf6
    style D fill:#c4b5fd,color:#1e1b4b,stroke:#a78bfa

예시: 저장된 인증 정보가 SKIP_BUILD_NUMBER_BUMP=true 그러나 __CAPGO_KEEP_0__ 플래그를 전달 --no-skip-build-number-bump CLI에서 CLI flag이 우선되고 빌드 번호는 자동으로 증가합니다.

Tip

CI/CD pipeline의 경우 환경 변수가 가장 편리합니다. 로컬 개발의 경우 저장된 자격 증명(위치) build credentials saveiOS 옵션

---

__CAPGO_KEEP_0__ Signing

Code

CLI Flag	__CAPGO_KEEP_0__	__CAPGO_KEEP_1__	기본값	설명
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64 인코딩 .p12 분산 인증서
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	확장 프로그램으로 구성된 앱의 path 또는 bundleId=path __CAPGO_KEEP_0__ 플래그
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	설명 .p12 인증서 (인증서가 암호가 없으면 생략)

앱 스토어 연결 인증

CLI Flag	환경 변수	인증 키	기본	설명
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	앱 스토어 연결 API 키 ID
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	앱 스토어 연결 발급자 ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64 인코딩된 앱 스토어 연결 API 키 (.p8 파일)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	앱 스토어 연결 팀 ID

권장하지 않음

앱별 비밀번호 인증은 권장되지 않으며 사용을 피하는 것이 좋습니다. It exists only as a compatibility path for teams migrating from Ionic Appflow (which relied on it). It is tied to a personal Apple ID with no granular permissions, cannot query App Store Connect (so build numbers fall back to a timestamp), and only covers the TestFlight upload itself. Prefer an App Store Connect API key (.p8App Store Connect에 대한 granular 권한이 없는 개인 Apple ID와 연결되어 있으며 App Store Connect에 대한 쿼리도 할 수 없으므로 빌드 번호는 타임스탬프로 돌아갑니다. TestFlight 업로드만 커버합니다. App Store Connect __CAPGO_KEEP_0__ 키 (

)를 사용하는 것이 권장되는, 더 강력하고 더 안전한 CI/CD 옵션입니다.

CLI Flag	__CAPGO_KEEP_0__ Flag	환경 변수	인증 키	기본
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	설명
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	앱을 소유한 계정의 Apple ID 이메일xxxx-xxxx-xxxx-xxxx앱별 비밀번호 ( appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	숫자 App Store Connect 앱 ID (예:) 1234567890)

주의

모든 세 가지 필드는 함께 필요합니다. 숫자는 필수입니다: 없으면 fastlane은 build runner에서 완료할 수 없는 인터랙티브 2FA 로그인으로 돌아갑니다. 이 방법을 사용할 때 build 번호는 timestamp-based 값으로 돌아갑니다, App Store Connect에서 최신 build 번호를 조회하지 때문입니다. APPLE_APP_ID iOS 빌드 설정

제목 "iOS 빌드 설정"

CLI Flag	인증 키	기본	Section	설명
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode scheme을 빌드하기 위해
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode 빌드 설정을 읽기 위해
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	배포 모드: app_store 또는 ad_hoc

---

안드로이드 옵션

키스토어 인증

CLI 플래그	환경 변수	인증 키	기본값	설명
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64 인코딩 키스토어 파일 (.keystore 또는 .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	키스토어 키 별칭
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	키스토어 키 비밀번호 (스토어 비밀번호로 자동 대체)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	키스토어 스토어 비밀번호

구글 플레이 구성

CLI 플래그	환경 변수	인증 키	기본값	설명
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64 인코딩 Google Play 서비스 계정 JSON 키
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (또는 production 과 --submit-to-store-review)	Google Play 릴리스 트랙 (internal, alpha, beta, production). Forwarded from CI env / CLI into the build runner.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft CI 환경에서 전달 / __CAPGO_KEEP_0__에서 빌드 러너로 전달됨. completed (또는 --submit-to-store-review)	과draft, completed, inProgress, halted선택한 트랙에서 릴리스 상태 ( --submit-to-store-review )

안드로이드 빌드 설정

CLI 플래그	기본	설명
--android-flavor <flavor>	—	빌드할 제품 맛을 선택하세요 (예: production). 필수 프로젝트에서 여러 맛을 정의한 경우.
--android-track <track>	internal	이 업로드에 사용할 구글 플레이 트랙입니다. 트랙이 설정되지 않은 경우 __CAPGO_KEEP_0__은 --submit-to-store-review 이 업로드에 사용할 구글 플레이 릴리즈 상태입니다. 상태가 설정되지 않은 경우 Capgo은 production.
--android-release-status <status>	draft	기본 --submit-to-store-review and no status set, Capgo defaults to completed.
--in-app-update-priority <0–5>	—	Google Play 내 앱 업데이트 우선순위 (높을수록 더 급합니다.)
--no-playstore-upload	—	빌드하고 서명하지만 Play Store 업로드를 건너뛰세요 (이용하려면) --output-upload).

---

빌드 제어 옵션

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

빌드 모드

CLI 플래그	기본	설명
--platform <platform>	—	필수입니다. ios 또는 (Appflow 플러그인 또는 Capawesome 플러그인 중 하나를 선택하세요.) android
--build-mode <mode>	release	debug 또는 release
--path <path>	.	프로젝트 디렉토리
--verbose	false	Verbose 빌드 로깅 활성화
--ai-analytics	false	빌드 실패 시 로그를 Capgo AI로 전송하여 진단 — 자세히 보기 AI 빌드 진단

빌드 번호 관리

CLI 플래그	환경 변수	인증 키	기본	설명
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	자동 빌드 번호/버전 code 자동 증가를 건너뜀
--no-skip-build-number-bump	—	—	—	자동 증가 재 활성화 (저장된 자격 증명에 의해 덮어씌움)

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

• iOS: 애플 스토어 커넥트에서 최신 빌드 번호를 가져와 1을 증가시킵니다
• Android: Google Play에서 max를 가져와 1을 증가시킵니다 versionCode 설정된 경우, 빌드는 프로젝트 파일(Xcode 프로젝트 또는

출력 업로드 --skip-build-number-bump 출력 업로드 build.gradle).

Output Upload

CLI 플래그	환경 변수	인증 키	기본값	설명
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Capgo 저장소에 IPA/APK/AAB 빌드 출력을 업로드합니다. 환경 변수를 통해 설정할 경우 사용 BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	출력 업로드를 비활성화합니다. 환경 변수를 통해 설정할 경우 사용 BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	다운로드 링크 활성 시간
--output-record <path>	—	—	—	빌드가 성공적으로 완료된 후, JSON 레코드 (작업 ID, 상태, 다운로드 URL, QR code)를 기록합니다. <path> — 환경 변수를 통해 읽어올 수 있습니다. build last-output.

보존 형식: 인간이 읽을 수 있는 시간 형식 사용 1h, 6h, 2d, 7d최소 1시간, 최대 7일입니다. 환경 변수를 통해 설정할 경우 초 단위 (예: 1시간)를 사용하세요. 3600 캐시 빌드

캐시 빌드 섹션

Capgo saves compiled native artifacts (CocoaPods, Gradle, and related build outputs) 이러한 아티팩트를 저장함으로써 반복 빌드는 더 빠르게 시작됩니다. 캐시 빌드는 기본적으로 각 앱에 대해 활성화되어 있습니다. __CAPGO_KEEP_0__ 플래그 __CAPGO_KEEP_0__ 필드

CLI Flag	API field	__CAPGO_KEEP_0__ 플래그	설명
--no-cache	cache_enabled: false	캐시 켜기	이 빌드에 대한 캐시 사용 중지: 저장 복원 생략 그리고 새 항목 저장하지 않음
--cache-key <value>	cache_key	(생략)	캐시 분할 (예를 들어 prod, staging) 하나의 공유 일반 캐시를 위해 생략

CLI 동등 항목: build request 수락 --no-cache 그리고 --cache-key.

Tip

다른 --cache-key RC와 프로덕션 빌드가 동일한 앱 ID를 공유하지만 서로의 컴파일된 출력을 재사용하지 않도록 하려면 — 예를 들어 --cache-key=prod 및 --cache-key=staging.

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 / 웹후크 페이로드 (당신의 통합이 Capgo 빌드 직접 호출할 때):

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

생략 cache_key 공유 일반 캐시를 위해 cache_key 환경에 따라 분할하기. 설정 "cache_enabled": false 단일 요청에 대해 캐시를 비활성화하려면 (같은 것) --no-cache).

빌드가 성공적으로 보이지만 아티팩트가 잘못된 경우 — 또는 RC vs 프로덕션에서 Android AAB가 누락된 경우 — 전용 캐시 키 또는 일회용 빌드를 시도하십시오. 자세히 보기 --no-cache 오류 복구: 잘못된 캐시 복원 인증.

제목 "인증"

CLI Flag	기본	설명	__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 인증을 위한 키
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API key for authentication
--supa-host <host>	—	—	개인 호스팅 전용: 사용자 정의 Supabase 호스트
--supa-anon <key>	—	—	개인 호스팅 전용: 사용자 정의 Supabase anon 키

---

환경 변수 빠른 참조

CI/CD pipeline에 복사-붙여넣기 가능한 환경 변수입니다. 모든 변수는 선택 사항이며 필요할 때만 설정합니다.

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"

안드로이드

# 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"

---

인증 정보 저장소

지역 저장소에 인증 정보 저장

플래그나 환경 변수를 매번 전달하는 대신, 인증 정보를 한 번 저장하세요:

# 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

저장 위치

기호	Flag	위치
Location	~/.capgo-credentials/credentials.json	사용 사례
--local	.capgo-credentials.json Use Case	(기본)

(default) 전역 — 모든 프로젝트에 공유 Global — shared across all projects on your machine com.example.myapp이러한 설정 파일은 여러 앱을 위한 설정을 저장할 수 있으므로 충돌이 발생하지 않습니다. 각 앱의 설정은 플랫폼별로 나누어집니다 (ios / android).

주의

로 추가하세요. 로컬 인증서를 사용하는 경우에는 버전 관리에 포함시키지 마세요. .capgo-credentials.json 저장된 인증서 관리 .gitignore 저장된 인증서 관리 섹션

터미널 창

# 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 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 플래그 직접 사용

# 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

__CAPGO_KEEP_0__ override와 저장된 자격 증명을 combine

Combine saved credentials with CLI overrides:

# 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 플래그는 이 특정 실행에 대한 빌드 동작을 오버라이드합니다.