Opsi Konfigurasi

Referensi lengkap untuk setiap opsi konfigurasi Cloud Build. Gunakan halaman ini untuk mencari flag CLI, variabel lingkungan, atau key kredensial untuk pengaturan build apa pun.

Urutan Prioritas Konfigurasi

Setiap opsi build dapat diatur dengan berbagai cara. Jika opsi yang sama diatur di beberapa tempat, sumber dengan prioritas lebih tinggi yang akan menang:

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

Contoh: Jika kredensial tersimpan Anda memiliki SKIP_BUILD_NUMBER_BUMP=true tetapi Anda menyertakan --no-skip-build-number-bump pada CLI, flag CLI akan menang dan nomor build akan bertambah secara otomatis.

Tips

Untuk pipeline CI/CD, environment variables biasanya paling praktis. Untuk pengembangan lokal, kredensial tersimpan (via build credentials save) mencegah pengulangan flag setiap saat.

---

Opsi iOS

Penandatanganan Code

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64-encoded .p12 sertifikat distribusi
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	Provisioning profile sebagai path atau bundleId=path mapping. Bisa diulang untuk aplikasi multi-target (app + extensions); nama profil akan diekstrak otomatis.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Password untuk .p12 sertifikat (kosongkan jika sertifikat tidak pakai password)

Autentikasi App Store Connect

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	ID Kunci App Store Connect API
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect Issuer ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Kunci API App Store Connect terenkripsi Base64 (.p8 file)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	Team ID App Store Connect

Tidak direkomendasikan

Autentikasi kata sandi khusus aplikasi tidak disarankan dan sebaiknya tidak digunakan. Ini hanya tersedia sebagai jalur kompatibilitas bagi tim yang migrasi dari Ionic Appflow. Metode ini terikat ke Apple ID pribadi tanpa izin granular, tidak bisa query App Store Connect (sehingga build number akan menggunakan timestamp), dan hanya mencakup proses upload TestFlight saja. Gunakan kunci API App Store Connect (.p8) sebagai gantinya: ini adalah opsi yang lebih direkomendasikan, lebih mumpuni, dan lebih aman untuk CI/CD.

Autentikasi app-specific password (tidak disarankan)

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Email Apple ID dari akun pemilik aplikasi
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Kata sandi khusus aplikasi (xxxx-xxxx-xxxx-xxxx) yang dibuat di appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	ID aplikasi App Store Connect numerik (misal. 1234567890)

Peringatan

Ketiga field ini wajib diisi bersamaan. Nilai numerik APPLE_APP_ID (ditemukan di App Store Connect → app Anda → App Information → Apple ID) bersifat wajib: tanpa ini, fastlane akan beralih ke login 2FA interaktif yang tidak bisa diselesaikan di build runner. Jika metode ini digunakan, build number akan menggunakan nilai berbasis timestamp, karena App Store Connect tidak akan ditanya untuk mendapatkan build number terbaru.

Pengaturan Build iOS

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode scheme untuk build
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Target Xcode untuk membaca build settings
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Mode distribusi: app_store atau ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	apa saja	Build dengan versi Xcode ini, misalnya 26, 26.0.1 atau 27Versi mayor mencakup semua versi minor. Build akan langsung gagal dan menampilkan daftar versi yang tersedia jika tidak ada yang cocok.

Xcode 27

Build dengan Xcode 27 (iOS 27 SDK) dengan --xcode-version 27:

npx @capgo/cli@latest build request --platform ios --xcode-version 27

Aplikasi yang di-build dengan iOS 27 SDK harus menggunakan UIScene lifecycle: tanpa UIApplicationSceneManifest di Info.plist dan scene delegate, iOS 27 akan menghentikan aplikasi saat launch. Capgo memblokir build ini sebelum dimulai (pemeriksaan prescan ios/plist-scene-lifecycle-xcode27). Tambahkan SceneDelegate dan UIApplicationSceneManifest ke ios/App/App/Info.plist, atau lanjut build dengan --xcode-version 26 sampai Anda melakukannya. Lihat panduan scene lifecycle dari Apple.

Akhir dukungan CocoaPods (Desember 2026)

Capgo Build akan menghentikan proses build proyek iOS yang menggunakan CocoaPods pada Desember 2026. Migrasikan proyek Anda ke Swift Package Manager sebelum itu: lihat Panduan Capacitor SPM. Sampai saat itu, build CocoaPods tetap berjalan; CLI akan menampilkan peringatan dan Capgo akan mengirim email pengingat ke admin organisasi Anda.

---

Opsi Android

Penandatanganan Keystore

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	File keystore terenkripsi Base64 (.keystore atau .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias kunci Keystore
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Password kunci Keystore (menggunakan password store jika tidak diatur)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Password store keystore

Konfigurasi Google Play

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	JSON key service account Google Play dalam format Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (atau production dengan --submit-to-store-review)	Track rilis Google Play (internal, alpha, beta, production). Diteruskan dari env CI / CLI ke build runner.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (atau completed dengan --submit-to-store-review)	Status rilis pada track yang dipilih (draft, completed, inProgress, halted). Nilai eksplisit akan menimpa --submit-to-store-review default.

Pengaturan Android Build

Flag CLI	Default	Deskripsi
--android-flavor <flavor>	—	Product flavor yang akan di-build (misal: production). Wajib jika proyek Anda memiliki beberapa flavor.
--android-track <track>	internal	Google Play track untuk upload ini. Jika --submit-to-store-review and no track set, Capgo defaults to production.
--android-release-status <status>	draft	status rilis Google Play. Jika --submit-to-store-review and no status set, Capgo defaults to completed.
--in-app-update-priority <0–5>	—	prioritas in-app update Google Play untuk rilis ini (lebih tinggi = lebih mendesak).
--no-playstore-upload	—	Build dan sign, tapi lewati upload ke Play Store (butuh --output-upload).

---

Opsi Kontrol Build

Opsi ini berlaku untuk build iOS maupun Android.

Mode Build

Flag CLI	Default	Deskripsi
--platform <platform>	—	Wajib diisi. ios atau android
--build-mode <mode>	release	debug atau release
--path <path>	.	Direktori proyek
--verbose	false	Aktifkan verbose build logging
--ai-analytics	false	Jika build gagal, kirim logs ke Capgo AI untuk diagnosis — lihat Diagnosis Build AI

Kontrol Build Number

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Lewati auto-increment build number / versi code
--no-skip-build-number-bump	—	—	—	Aktifkan kembali auto-increment secara eksplisit (menimpa kredensial tersimpan)

Secara default, Capgo Cloud Build akan otomatis menaikkan build number:

• iOS: Mengambil nomor build terbaru dari App Store Connect, lalu ditambah 1
• Android: Mengambil nilai max versionCode dari Google Play, lalu ditambah 1

Saat --skip-build-number-bump sudah diatur, build akan menggunakan versi yang ada di file proyek Anda (proyek Xcode atau build.gradle).

Upload Output

Flag CLI	Variabel Env	Key Kredensial	Default	Deskripsi
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Upload hasil build (IPA/APK/AAB) ke penyimpanan Capgo. Jika diatur via env var, gunakan BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Nonaktifkan upload output. Jika diatur via env var, gunakan BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Lama masa aktif link download
--output-record <path>	—	—	—	Setelah build berhasil, tulis record JSON (job ID, status, download URL, QR code) ke <path> — baca kembali menggunakan build last-output.

Format retensi: Gunakan durasi yang mudah dibaca seperti 1h, 6h, 2d, 7d. Minimal 1 jam, maksimal 7 hari. Jika diatur via env var, gunakan detik (misal, 3600 untuk 1 jam).

Cache build

Capgo menyimpan artefak native yang sudah dikompilasi (CocoaPods, Gradle, dan output build terkait) per aplikasi agar proses build ulang jadi lebih cepat. Build cache diaktifkan secara default untuk setiap aplikasi.

Flag CLI	Field API	Default	Deskripsi
--no-cache	cache_enabled: false	cache aktif	Nonaktifkan cache untuk build ini: skip restore dan jangan simpan entri baru
--cache-key <value>	cache_key	(lewati)	Partisi cache (misalnya prod, staging). Lewati untuk satu cache umum per aplikasi

setara dengan CLI: build request menerima --no-cache dan --cache-key.

Tips

Gunakan yang berbeda --cache-key saat build RC dan produksi menggunakan app ID yang sama tetapi tidak boleh menggunakan output kompilasi satu sama lain — misalnya --cache-key=prod dan --cache-key=staging.

Contoh 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 / payload webhook (saat integrasi Anda memanggil Capgo Build secara langsung):

{
  "platform": "android",
  "cache_key": "prod"
}

Hilangkan cache_key untuk cache general bersama. Atur cache_key untuk partisi berdasarkan environment. Atur "cache_enabled": false untuk menonaktifkan cache pada satu request (sama dengan --no-cache).

Jika build terlihat sukses tapi artifact-nya salah — atau Android AAB hilang setelah beralih RC vs production — coba dedicated cache key atau one-off --no-cache build. Lihat Troubleshooting: restore cache yang salah.

Autentikasi

Flag CLI	Variabel Env	Default	Deskripsi
-a, --apikey <key>	CAPGO_TOKEN	—	Kunci Capgo API untuk autentikasi
--supa-host <host>	—	—	Host Supabase kustom (hanya self-hosting)
--supa-anon <key>	—	—	Anon key Supabase kustom (hanya self-hosting)

---

Referensi Cepat Environment Variable

Siap copy-paste untuk pipeline CI/CD Anda. Semua variabel bersifat opsional — cukup set yang Anda butuhkan.

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"
CAPGO_IOS_XCODE_VERSION="27"

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"

Kontrol Build

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

---

Penyimpanan Kredensial

Simpan Kredensial Lokal

Daripada memasukkan flag atau env vars setiap saat, simpan kredensial sekali saja:

# 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

Lokasi Penyimpanan

Flag	Lokasi	Kasus Penggunaan
(default)	~/.capgo-credentials/credentials.json	Global — dibagikan ke semua proyek di mesin Anda
--local	.capgo-credentials.json di root proyek	Per-proyek — menimpa konfigurasi global jika keduanya ada

Kredensial dikelompokkan berdasarkan ID aplikasi (mis. com.example.myapp), sehingga satu file kredensial dapat menyimpan pengaturan untuk banyak aplikasi tanpa konflik. Kredensial setiap aplikasi kemudian dipisah berdasarkan platform (ios / android).

Peringatan

Tambah .capgo-credentials.json ke .gitignore jika menggunakan kredensial lokal. Jangan pernah commit kredensial ke version control.

Kelola Kredensial Tersimpan

# 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

---

Contoh

Aksi 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 }}

Menggunakan Flag CLI Secara Langsung

# 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

Konfigurasi Campuran

Gabungkan kredensial tersimpan dengan override 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

Kredensial tersimpan menyediakan detail signing, sementara flag CLI akan meng-override perilaku build untuk run spesifik ini.