설정 옵션

Complete reference for every Cloud Build configuration option. Use this page to find the CLI flag, environment variable, or credential key for any build setting.

구성 설정 순위

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

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 on the CLI, the CLI flag wins and build numbers will be auto-incremented.

CI/CD PIPELINES의 경우, 환경 변수가 가장 편리합니다. 로컬 개발의 경우, 저장된 인증서(위아래)

For CI/CD pipelines, environment variables are usually the most convenient. For local development, saved credentials (via build credentials save반복적인旗를 피하세요.

---

iOS 옵션

Code 서명

CLI 플래그	환경 변수	인증 키	기본	설명
--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 맵핑. 다중 대상 앱 (앱 + 확장) 에서 반복 가능; 프로파일 이름은 자동으로 추출됩니다.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	앱 스토어 연결 인증서의 .p12 인증서가 암호가 없는 경우 생략할 수 있는 암호

앱 스토어 연결 인증

CLI 플래그	환경 변수	인증 키	기본	설명
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API Key ID
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect 발급자 ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded App Store Connect API key (.p8 파일)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 팀 ID

사용하지 않는 것을 권장합니다.

App Store Connect __CAPGO_KEEP_0__ 키 대신 앱별 암호 인증을 사용하는 것은 비추이며 사용을 피하는 것이 좋습니다. 이것은 Ionic Appflow (이것은 그것에 의존했습니다)에서 팀이 이주하는 호환성 경로로만 존재합니다. 이것은 개인 Apple ID와 granular 권한이 없는 것으로 묶여 있으며 App Store Connect (이러한 빌드 번호는 시간戳로 돌아가므로)와의 쿼리를 할 수 없으며 TestFlight 업로드만을 위한 것입니다. App Store Connect API 키 대신 (.p8)을 사용하는 것이 좋습니다. 그것은 CI/CD에 권장되는, 더 강력하고 더 안전한 옵션입니다.

앱별 암호 인증 (권장하지 않는 것)

CLI Flag	환경 변수	인증 키	기본	설명
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	애플 ID 이메일
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	앱 스토어 연결 앱 ID (xxxx-xxxx-xxxx-xxxx) 애플 ID 앱 스토어 연결 앱 ID
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	주의 1234567890)

앱 스토어 연결 앱 ID (예:

All three fields are required together. The numeric APPLE_APP_ID (found in App Store Connect → your app → App Information → Apple ID) is mandatory: without it fastlane falls back to an interactive 2FA login that cannot complete on the build runner. When this method is used the build number falls back to a timestamp-based value, because App Store Connect is not queried for the latest build number.

iOS 빌드 설정

CLI Flag	환경 변수	인증 키	기본	설명
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	빌드할 Xcode 스키마
--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

---

안드로이드 옵션

Keystore 인증

CLI 플래그	환경 변수	인증 키	기본	설명
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64로 인코딩된 Keystore 파일 (.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	—	키 저장소 저장소 암호

Google Play 구성

CLI Flag	환경 변수	인증 키	기본	설명
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64 인코딩 Google Play 서비스 계정 JSON 키
(환경 변수 전용)	PLAY_STORE_TRACK	—	internal	Google Play 출시 트랙 (internal, alpha, beta, production)
(환경 변수만)	PLAY_STORE_RELEASE_STATUS	—	draft	선택한 트랙에서 출시 상태 (draft, completed, inProgress, halted)

Android 빌드 설정

CLI 플래그	기본	설명
--android-flavor <flavor>	—	빌드할 제품 플래버 (예: production). 필수 프로젝트에 여러 플래버가 정의되어 있다면.
--in-app-update-priority <0–5>	—	Google Play 내 앱 업데이트 우선순위 (더 높을수록 더 급함).
--no-playstore-upload	—	Build 및 Play Store 업로드를 생략하여 빌드하고 서명하세요 (iOS 및 Android 빌드에 모두 적용됩니다.) --output-upload).

---

빌드 제어 옵션

iOS 및 Android 빌드에 모두 적용됩니다.

빌드 모드

CLI 플래그	기본	설명
--platform <platform>	—	필수. ios 또는 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	—	—	—	explicitly 재 활성화 자동 증가 (저장된 자격 증명에 의해 오버 라이드 됨)

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

• iOS: 최신 빌드 번호를 App Store Connect에서 가져와 1을 증가시킵니다
• Android: Google Play에서 가져온 max versionCode 에서 1을 증가시킵니다

설정되면 빌드는 프로젝트 파일 (Xcode 프로젝트 또는 --skip-build-number-bump 출력 업로드 build.gradle).

출력 업로드

CLI Flag	환경 변수	인증 키	기본	설명
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	IPA/APK/AAB 빌드 출력을 Capgo 저장소에 업로드합니다. 환경 변수를 통해 설정할 경우 사용 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.

보존 형식: 인간이 읽을 수 있는 시간 단위 (예: 1시간, 3일 등)를 사용합니다. 최소 1시간, 최대 7일입니다. 환경 변수를 통해 설정할 경우 초 단위 (예: 3600, 604800 등)를 사용합니다. 1h, 6h, 2d, 7d. Minimum is 1 hour, maximum is 7 days. When set via env var, use seconds (e.g., 3600 1시간 동안 작동합니다.

인증

CLI Flag	환경 변수	기본	설명
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API 인증을 위한 키
--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"

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"

---

인증 정보 저장소

지역 저장소

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

# 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.json	전역 — 모든 프로젝트에 걸쳐서 컴퓨터에 설치된
--local	.capgo-credentials.json 프로젝트 루트	프로젝트별 — 전역과 함께 존재할 때 오버라이드

인증 정보는 키로 구성되며 앱 ID (예를 들어, com.example.myapp), 따라서 단일 인증 파일은 여러 앱의 설정을 저장할 수 있으며 충돌이 발생하지 않습니다. 각 앱의 인증 정보는 플랫폼별로 나누어집니다 (ios / android).

주의

추가 .capgo-credentials.json __CAPGO_KEEP_0__ .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 액션

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

혼합 설정

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 플래그가 있으면 저장된 자격 증명은 서명 세부 정보를 제공합니다.