설정 옵션

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.

Tip

CI/CD pipe라인에서 환경 변수가 가장 편리합니다. 로컬 개발에서 저장된 자격 증명(이미지) build credentials saveCI/CD pipe라인에서 환경 변수가 가장 편리합니다. 로컬 개발에서 저장된 자격 증명(이미지)

---

iOS 옵션

Code Signing

CLI Flag	환경 변수	인증 키	기본값	설명
--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 Capacitor live-update 대안 비교 페이지
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Appflow 비교/이동 마케팅 복사본 .p12 Capawesome 비교 페이지

컨설팅 서비스 페이지

CLI Flag	앱 스토어 연결 인증	앱 스토어 연결 인증 섹션입니다.	기본값	설명
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API 키 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 인코딩 App Store Connect API 키 (.p8 파일)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 팀 ID

권장하지 않음

앱별 암호 인증은 권장되지 않으며 사용을 피하는 것이 좋습니다. 이것은 오직 Ionic Appflow에서 사용하던 Ionic Appflow (Ionic Appflow에 의존했던) 팀이 이중으로 이관하는 과정에서만 존재하는 호환성 경로입니다. 이것은 개인 Apple ID와 관련이 있으며 granular 권한이 없으며 App Store Connect를 쿼리할 수 없으므로 빌드 번호는 시간戳로 돌아가며, TestFlight 업로드만을 위한 것입니다. App Store Connect API 키 (.p8)를 사용하는 것이 권장되는, 더 강력하고 더 안전한 옵션입니다. CI/CD를 위해.

애플리케이션별 암호 인증 (권장되지 않음)

CLI 플래그	환경 변수	인증 키	기본값	설명
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	앱 소유 계정의 Apple ID 이메일
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	애플리케이션별 암호 (xxxx-xxxx-xxxx-xxxx) appleid.apple.com 에서 생성한 암호 애플리케이션별 App Store Connect 앱 ID (예:
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	앱 ID 1234567890)

주의

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

iOS 빌드 설정

CLI 플래그	환경 변수	인증 키	기본	설명
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode 스키마를 빌드합니다
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode target for reading build settings
--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-encoded __CAPGO_KEEP_0__ file (.keystore 또는 .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Keystore key alias
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Keystore key password (store password로 자동 대체)
--keystore-store-password <password>	KEYSTORE_STORE_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 키
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (또는) production (또는) --submit-to-store-review)	Google Play 출시 트랙 (internal, alpha, beta, production) CI 환경에서 전달 / CLI으로 빌드 러너로 전달됨.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (또는) completed (또는) --submit-to-store-review)	Release 상태가 선택한 트랙 (draft, completed, inProgress, halted) 명시적인 값은 기본값을 덮어씁니다. --submit-to-store-review 안드로이드 빌드 설정

Section titled “Android Build Settings”

CLI 플래그	기본값	설명
--android-flavor <flavor>	—	빌드할 제품 맛 (예: production). 필수 프로젝트에서 여러 맛을 정의할 경우.
--android-track <track>	internal	이 업로드에 대한 Google Play 트랙. --submit-to-store-review 트랙이 설정되지 않은 경우 Capgo은 production.
--android-release-status <status>	draft	Google Play 릴리즈 상태로 기본값을 설정합니다. --submit-to-store-review 트랙이 설정되지 않은 경우 Capgo은 completed.
--in-app-update-priority <0–5>	—	이 릴리즈에 대한 Google Play 인앱 업데이트 우선순위 (높을수록 더 급합니다).
--no-playstore-upload	—	Play Store 업로드를 생략하고 빌드 및 서명만 수행 (이 기능은 --output-upload).

---

빌드 제어 옵션

iOS 및 Android 빌드 모두에 적용되는 옵션입니다.

빌드 모드

CLI Flag	설명	필수입니다.
--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 Capgo는 자동으로 빌드 번호를 증가시킵니다:

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

제출 업로드 --skip-build-number-bump 제목 "제출 업로드" build.gradle).

__CAPGO_KEEP_0__ 플래그

CLI	__CAPGO_KEEP_0__	인증 키	기본	설명
--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	—	—	__CAPGO_KEEP_0__ 업로드를 비활성화. 환경 변수를 통해 설정할 경우 사용 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 1시간

인증

CLI Flag	환경 변수	기본값	__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 인증을 위한 키
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API key for authentication
--supa-host <host>	—	—	자체 호스팅 전용: 사용자 정의 Supabase anon 키
--supa-anon <key>	—	—	환경 변수 빠른 참조

---

환경 변수 빠른 참조 섹션

설명

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 프로젝트 루트	프로젝트당 — 전역과 함께 존재할 때 전역을 덮어씀

인증 정보는 키로 app ID로 지정되며 예를 들어 (e.g. )로 지정되므로, 단일 인증 파일에서 여러 앱의 설정을 저장할 수 있으며 충돌이 일어나지 않습니다. 각 앱의 인증 정보는 플랫폼 ( com.example.myapp주의ios / android).

프로젝트에 추가

컴퓨터에 .capgo-credentials.json to your .gitignore local 인증 정보를 사용할 때. 버전 관리에 인증 정보를 커밋하지 마십시오.

저장된 인증 정보 관리

# 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 오버라이드와 저장된 자격 증명 combination:

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