__CAPGO_KEEP_0__ 구성 옵션

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 PIPELINE에서 환경 변수가 가장 편리합니다. 로컬 개발 시 저장된 인증 정보 (via )를 사용하면 매번 플래그를 반복하지 않아도 됩니다. build credentials saveCI/CD PIPELINE에서 환경 변수가 가장 편리합니다. 로컬 개발 시 저장된 인증 정보 (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	—	__CAPGO_KEEP_0__ 비밀번호 .p12 인증서 (인증서가 비밀번호가 없으면 생략)

앱 스토어 연결 인증

CLI 플래그	환경 변수	인증 키	기본	설명
--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	—	API 키 (Base64-인코딩 App Store Connect "file").p8 App Store Connect 팀 ID
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	주의

대안 인증:

Apple ID + 앱 전용 암호 대신 __CAPGO_KEEP_0__ 키를 사용할 수 있습니다. Pass You can also use Apple ID + app-specific password instead of API keys. Pass --apple-id <email> (환경 변수: --apple-app-specific-password <password> ). __CAPGO_KEEP_0__ 키는 CI/CD에 권장됩니다. APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD). API keys are recommended for CI/CD.

__CAPGO_KEEP_0__

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

---

안드로이드 옵션

__CAPGO_KEEP_0__ Flag

CLI Flag	환경 변수	인증 키	기본	설명
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64-encoded keystore 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 (falls back to store password if not set)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Keystore store password

Google Play 설정

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

안드로이드 빌드 설정

CLI 플래그	기본	설명
--android-flavor <flavor>	—	프로덕트 플래버를 빌드합니다 (예: production). 필수 프로젝트가 여러 플래버를 정의하는 경우.
--in-app-update-priority <0–5>	—	Google Play 내 앱 업데이트 우선순위 (높을수록 더 급합니다).
--no-playstore-upload	—	빌드 및 서명하지만 Play Store 업로드를 생략합니다 (Cloudflare에 대한 SDK가 필요합니다). --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로 로그를 보내고 진단을 확인하세요 — 인공지능 빌드 진단

빌드 번호 관리

CLI 플래그	환경 변수	인증 키	기본	설명
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	code 자동 빌드 번호/버전 증가를 생략합니다.
--no-skip-build-number-bump	—	—	—	자동 증가를 다시 활성화합니다(저장된 인증 정보를 덮어씁니다).

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

• iOS: __CAPGO_KEEP_0__ Flag
• Android: Fetches max versionCode from Google Play, increments by 1

When --skip-build-number-bump is set, the build uses whatever version that is already in your project files (Xcode project or build.gradle).

Output Upload

CLI Flag	Credential Key	Default	__CAPGO_KEEP_0__ Flag	설명
--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.

보존 형식: 인간이 읽을 수 있는 시간 단위 (예: 1시간, 7일)를 사용합니다. 1h, 6h, 2d, 7d1시간에서 7일까지의 최소/최대 시간입니다. 환경 변수를 통해 설정할 경우 초 단위 (예: 3600초)를 사용합니다. 3600 인증

인증

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"

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

---

인증 정보 저장

__CAPGO_KEEP_0__ 로컬로 저장

__CAPGO_KEEP_1__ 대신 매번 플래그나 환경 변수를 전달하지 말고, 한번에 저장하세요.

# 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_KEEP_3__ 저장 위치

__CAPGO_KEEP_5__	__CAPGO_KEEP_6__	__CAPGO_KEEP_7__ (기본값)
__CAPGO_KEEP_8__ — 모든 프로젝트에 걸쳐서 컴퓨터에 저장됨.	~/.capgo-credentials/credentials.json	__CAPGO_KEEP_9__
--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 플래그는 이 특정 실행에 대한 빌드 동작을 오버라이드합니다.