구성 옵션

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

CI/CD PIPELINES의 경우, 환경 변수가 가장 편리합니다. 로컬 개발의 경우, 저장된 인증서 (via )는 매번 플래그를 반복하지 않도록 합니다.

iOS 옵션 build credentials saveiOS 옵션

---

__CAPGO_KEEP_0__ Signing

Code Signing

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 __CAPGO_KEEP_0__

앱 스토어 연결 인증

CLI 플래그	환경 변수	인증 키	기본	설명
--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-encoded 앱 스토어 연결 API 키 (.p8 파일)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 팀 ID

권장되지 않음

App Store Connect의 앱별 암호 인증은 권장되지 않으며 사용을 피하는 것이 좋습니다. Ionic Appflow (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	—	__CAPGO_KEEP_0__ 이메일
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	__CAPGO_KEEP_0__ 앱 전용 비밀번호 (xxxx-xxxx-xxxx-xxxx) appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	__CAPGO_KEEP_0__ (예: 1234567890)

주의

모든 세 가지 필드는 함께 필요합니다. 숫자 APPLE_APP_ID (App Store Connect → 앱 → 앱 정보 → Apple ID에서 찾을 수 있음) 은 필수입니다. 없으면 fastlane은 빌드 러너에서 완료할 수 없는 인터랙티브 2FA 로그인으로 돌아갑니다. 이 방법을 사용할 때 빌드 번호는 타임스탬프 기반 값으로 돌아갑니다. 왜냐하면 App Store Connect에서 최신 빌드 번호를 조회하지 않기 때문입니다.

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

---

안드로이드 옵션

지갑 암호화 인증

CLI Flag	환경 변수	인증 키	기본값	설명
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64-encoded keystore 파일 (.keystore 또는 .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Keystore 키 별칭
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Keystore 키 비밀번호 (기본값이 저장 비밀번호일 경우)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Keystore 저장 비밀번호

Google Play 구성

CLI 플래그	환경 변수	인증 키	기본	설명
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	구글 플레이 서비스 계정 JSON 키 (Base64 인코딩)
(환경 변수만)	PLAY_STORE_TRACK	—	internal	구글 플레이 릴리스 트랙 (internal, alpha, beta, production)
(환경 변수만)	PLAY_STORE_RELEASE_STATUS	—	draft	선택한 트랙에서 릴리스 상태 (draft, completed, inProgress, halted)

안드로이드 빌드 설정

CLI Flag	기본	설명
--android-flavor <flavor>	—	프로덕트 플래버를 빌드할 때 (예: production). 필수 프로젝트가 여러 플래버를 정의하는 경우.
--in-app-update-priority <0–5>	—	이 릴리즈에 대한 Google Play 내 앱 업데이트 우선순위 (높을수록 더 급함).
--no-playstore-upload	—	빌드 및 서명, 그러나 Play Store 업로드를 생략 (Cloudflare에 의존하는 경우에만 사용할 수 있음) --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	—	—	—	자동 증가를 명시적으로 다시 활성화합니다. (저장된 인증 정보를 덮어씁니다.)

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

• iOS: App Store Connect에서 최신 빌드 번호를 가져와 1을 증가시킵니다.
• 안드로이드: Fetches max versionCode Google Play에서 최대값을 가져오고 1을 더합니다.

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

출력 업로드

CLI 플래그	환경 변수	인증 키	기본	설명
--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.

보존 형식: 인간이 읽을 수 있는 시간 지연을 사용하십시오. 1h, 6h, 2d, 7d1시간 미만은 1시간, 7일 이상은 7일로 설정됩니다. 환경 변수를 통해 설정할 경우 초 단위 (예: 1시간)로 사용합니다. 3600 인증

인증 섹션

CLI	환경 변수	기본	설명
-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"

안드로이드

# 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 버전 관리에 인증 정보를 커밋하지 마십시오. .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 플래그는 이 특정 실행에 대한 빌드 동작을 오버라이드합니다.