配置选项

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.

Cloudflare

Cloud Build

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 每个构建选项都可以以多种方式设置。同一个选项在多个地方设置时，优先级更高的源会获胜： --no-skip-build-number-bump on the CLI, the CLI flag wins and build numbers will be auto-incremented.

如果您保存的凭据有

但是您传递了 build credentials save避免每次都重复标志。

---

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 __CAPGO_KEEP_0__ 标志

环境变量

CLI Flag	描述	App Store Connect Authentication	应用商店连接认证	Provisioning profile as a
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API Key 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 Team ID

不推荐

建议不要使用 App Store Connect 的 App 专用密码认证。 It exists only as a compatibility path for teams migrating from Ionic Appflow (which relied on it). It is tied to a personal Apple ID with no granular permissions, cannot query App Store Connect (so build numbers fall back to a timestamp), and only covers the TestFlight upload itself. Prefer an App Store Connect API key (.p8建议使用 App Store Connect __CAPGO_KEEP_0__ key (

）而不是它：它是推荐的、更强大的、更安全的 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
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	数字 App Store Connect 应用 ID（例如 1234567890)

注意

All three fields are required together. The numeric 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

---

安卓选项

密钥库签名

CLI 标志	环境变量	凭证密钥	默认	描述
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64编码的keystore文件（.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	—	密钥库存储密码

Google Play 配置

CLI 标志	环境变量	凭证密钥	默认	描述
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64编码的Google Play服务帐号JSON密钥
(env only)	PLAY_STORE_TRACK	—	internal	Google Play 发布渠道 (internal, alpha, beta, production)
(env only)	PLAY_STORE_RELEASE_STATUS	—	draft	选择的渠道上发布状态 (draft, completed, inProgress, halted)

Android 构建设置

CLI 标志	默认	描述
--android-flavor <flavor>	—	构建的产品风味 (例如 production). 必填 如果您的项目定义了多个风味。
--in-app-update-priority <0–5>	—	Google Play 内购更新优先级 (更高 = 更紧急)。
--no-playstore-upload	—	Build and sign, but skip the Play Store upload (requires --output-upload).

---

Build Control Options

These options work for both iOS and Android builds.

Build Mode

CLI Flag	Default	Description
--platform <platform>	—	or ios or android
--build-mode <mode>	release	debug or 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 号，递增 1

当 --skip-build-number-bump 设置时，构建使用项目文件中已经有的版本（Xcode 项目或 build.gradle).

输出上传

CLI 标志	环境变量	凭证密钥	默认	描述
--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 for 1 hour).

身份验证

CLI Flag	环境变量	默认	描述
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API 用于身份验证的密钥
--supa-host <host>	—	—	自主托管时的自定义 Supabase 主机
--supa-anon <key>	—	—	自主托管时的自定义 Supabase anon 密钥

---

环境变量快速参考

复制粘贴到您的CI/CD管道中。所有变量都是可选的 — 只设置您需要的变量。

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 (例如 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 直接标志

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