설정 옵션

모든 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 플래그가 우선되며 빌드 번호는 자동으로 증가합니다.

팁

CI/CD pipe라인에서, 환경 변수는 일반적으로 가장 편리합니다. 로컬 개발에서, 저장된 자격 증명 (via) build credentials save로컬 개발에서, 저장된 자격 증명 (via)

---

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 플래그	인증 키	기본	Default	설명
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	애플 스토어 연결 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-encoded 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에 의존했던)에서 팀이 이주하는 동안만 존재하는 호환성 경로입니다. 이것은 개인 Apple ID와 granular 권한이 없는 것으로 묶여 있으며 App Store Connect을 쿼리할 수 없기 때문에 빌드 번호는 시간 스탬프로 돌아가고, TestFlight 업로드만을 위한 것입니다. App Store Connect API 키 (.p8대신) 대신 사용하는 것이 권장됩니다: CI/CD에 대한 더 강력하고 더 안전한 옵션입니다.

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

CLI 플래그	환경 변수	인증 키	기본값	설명
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	앱 소유자 계정의 애플 ID 이메일
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	앱별 암호 (xxxx-xxxx-xxxx-xxxx) appleid.apple.com 에서 생성한 암호 숫자형 앱 스토어 연결 앱 ID (예:
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	주의 1234567890)

주의

모든 세 가지 필드는 함께 필요합니다. 숫자 APPLE_APP_ID App Store Connect → 앱 → 앱 정보 → Apple ID에서 찾을 수 있는 (App Store Connect → 앱 → 앱 정보 → Apple ID) 는 필수입니다: 이 필수 absence로 fastlane은 build runner에서 interactive 2FA 로그인으로 fallback 하며 완료할 수 없습니다. 이 방법을 사용할 때 build number는 timestamp-based value로 fallback 하며, App Store Connect에서 최신 build number를 조회하지 않습니다.

iOS 빌드 설정

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

---

Capacitor live-update alternatives 비교 페이지

__CAPGO_KEEP_0__ Flag

CLI 플래그	기본	설명	Default	Android Options
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Android 옵션.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	—	구글 플레이 서비스 계정 JSON 키 (Base64 인코딩)
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (또는 production 와 --submit-to-store-review)	구글 플레이 출시 트랙 (internal, alpha, beta, production). CI 환경에서 / CLI 에서 빌드 러너로 전달됩니다.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (또는 completed 와 --submit-to-store-review)	선택한 트랙에서 출시 상태 (draft, completed, inProgress, halted). 명시적인 값은 기본값을 덮어씁니다. --submit-to-store-review 안드로이드 빌드 설정

안드로이드 빌드 설정

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

---

Build Control Options이 필요합니다

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을 증가시킵니다.
• Android: Fetches max versionCode 설정된 경우, 프로젝트 파일(Xcode 프로젝트 또는)

출력 업로드 --skip-build-number-bump __CAPGO_KEEP_0__ 플래그 build.gradle).

환경 변수

CLI 플래그	Flag	Variable	기본값	설명
--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시간 이상, 7일 이하의 최소/최대 시간입니다. 환경 변수를 통해 설정할 경우 초 단위로 사용 (예: 1시간) 3600 빌드 캐시

__CAPGO_KEEP_0__

Capgo은 CocoaPods, Gradle 및 관련 빌드 출력과 같은 컴파일된 네이티브 아티팩트를 저장합니다. 앱당 따라서 반복 빌드는 더 빠르게 시작됩니다. 빌드 캐시는 기본적으로 활성화되어 있습니다 각 앱당

CLI 플래그	API 필드	기본값	설명
--no-cache	cache_enabled: false	캐시 활성화	이 빌드에 대한 캐시를 비활성화: 복원 생략 및 __CAPGO_KEEP_0__
--cache-key <value>	cache_key	(omit)	(예를 들어) prod, staging(예를 들어)

CLI 동등 항목: build request 수락 --no-cache 및 --cache-key.

팁

다른 --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).

설정 --no-cache 설정. 자세히 오류 해결: 잘못된 캐시 복원.

인증

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"

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로 키가 지정되므로, 단일 인증 파일에서 여러 앱의 설정을 저장할 수 있습니다. 플랫폼별로 앱의 인증 정보를 나누어 관리할 수 있습니다. 애플리케이션 ID app 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 플래그는 이 특정 실행에 대한 빌드 동작을 오버라이드합니다.