配置选项

Complete reference for every Cloud Build configuration option. Use this page to find the CLI flag, environment variable, or credential key for any build setting.

Configuration Precedence

Every build option can be set in multiple ways. When the same option is set in multiple places, higher-priority sources win:

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

Example: If your saved credentials have SKIP_BUILD_NUMBER_BUMP=true but you pass --no-skip-build-number-bump on the CLI, the CLI flag wins and build numbers will be auto-incremented.

提示

对于 CI/CD pipeline，环境变量通常是最方便的。对于本地开发，保存的凭据（通过）避免每次重复标志。 build credentials saveiOS 选项

---

标题：iOS 选项

标题：Code 签名

CLI Flag	凭据密钥	默认值	描述	For local development, saved credentials (via ) avoid repeating flags every time.
--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	—	App Store Connect认证 .p12 App Store Connect认证

__CAPGO_KEEP_0__标志

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-encoded App Store Connect API key (.p8 文件)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect 团队 ID

不建议使用

应用特定密码认证被建议避免，使用它是被建议的。 它仅作为 Ionic Appflow 迁移的兼容路径存在（它依赖于它）。它与一个没有细粒度权限的个人 Apple ID 关联，无法查询 App Store Connect（因此，构建号会回退到一个时间戳），并且仅覆盖 TestFlight 上传本身。建议使用 App Store Connect 的 API 密钥（.p8) 相反：它是CI/CD的推荐、更强大的、更安全的选项。

App专用密码认证（不推荐)

CLI Flag	环境变量	凭据密钥	默认值	描述
--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
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	数字App Store Connect应用ID（例如 1234567890)

注意

所有三个字段都必须同时存在。数字 APPLE_APP_ID (在 App Store Connect → 你的应用 → 应用信息 → Apple ID) 是必需的：没有它，fastlane 将回退到一个交互式 2FA 登录，无法在构建运行器上完成。当使用此方法时，构建号将回退到一个基于时间戳的值，因为 App Store Connect 不会为最新的构建号进行查询。

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 实时更新的替代方案

Capawesome

CLI Flag	Android 选项	Android 选项	Keystore 签名	Keystore 签名
--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	密钥库文件的Base64编码（
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	密钥库文件的Base64编码（
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	密钥库文件的Base64编码（

密钥库文件的Base64编码（

CLI Flag	__CAPGO_KEEP_0__ 标志	环境变量	凭据密钥	默认值
--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)	在选择的跟踪上设置的发布状态（draft, completed, inProgress, halted）。显式值会覆盖默认值。 --submit-to-store-review Android构建设置

标题为“Android构建设置”的部分

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	启用详细构建日志
--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: 从 Google Play 中获取最大值 versionCode 当

设置时，构建将使用项目文件中已经存在的版本（Xcode 项目或 --skip-build-number-bump 输出上传 build.gradle).

标题为“输出上传”

CLI Flag	__CAPGO_KEEP_0__	凭据密钥	默认	描述
--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, 7d. 最小值为 1 小时，最大值为 7 天。当通过环境变量设置时，使用秒数（例如， 3600 表示 1 小时）。

身份验证

CLI 标志	环境变量	默认值	描述
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API 身份验证密钥
--supa-host <host>	—	—	自主托管的 Supabase 主机 (自主托管)
--supa-anon <key>	—	—	自主托管的 Supabase 匿名密钥 (自主托管)

---

环境变量快速参考

复制并粘贴到您的 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

存储位置

标志	位置	使用场景(解决方案: Cordova 到 Capacitor AI )
(默认)	~/.capgo-credentials/credentials.json	全局 — 在您的机器上所有项目共享
--local	.capgo-credentials.json 在项目根目录	按项目 — 覆盖全局配置

凭据以应用 ID 为键 （例如 ），因此一个凭据文件可以存储多个应用的设置而无冲突。每个应用的凭据还根据平台进行分割（ com.example.myapp注意ios / android).

添加到您的

到您的 .capgo-credentials.json to your .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 flags 直接

# 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 标志则覆盖此特定运行的构建行为。