凭据管理

复制一个带有安装步骤和完整 Markdown 指南的设置提示。

在本地管理您的 iOS 和 Android 构建凭据，以便于云构建。

概述

Capgo CLI 存储您的构建凭据 在您的机器上 — 不在Capgo的服务器上。默认情况下，它们存储在一个全局文件 ~/.capgo-credentials/credentials.json, --local 所有项目共享。传递 来将它们 按项目 .capgo-credentials.json instead. When you run a build, the saved credentials are used automatically and sent securely to Capgo, then deleted after the build completes.

命令

交互式管理凭据

使用凭据管理器是快速工作与保存的凭据的方式。它打开一个 TUI（与您使用的相同的） build init 浏览存储的内容、查看每个应用程序和平台的配置、导出 CI/CD 准备好的文件或删除平台的凭据： .env 终端窗口

bunx @capgo/cli@latest build credentials manage

描述	要管理的应用程序（如果省略则提示您选择）
`--appId <appId>`	要管理的平台（如果省略则提示您选择）
`--platform <ios\|android>`	使用项目级别的
`--local`	而不是全局文件 `.capgo-credentials.json` targetLanguageCode

喜欢一次性、可脚本化的命令？使用以下单独命令。

保存凭据

将您的构建凭据存储在本地以便自动使用：

bunx @capgo/cli@latest build credentials save --platform <ios|android> [options]

更新凭据

部分更新现有凭据而无需重新提供所有内容：

bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]

The update command uses additive merge 用于配置文件 — 新配置文件与现有配置文件进行合并。要替换整个配置文件映射，请添加 --overwrite-ios-provisioning-map.

示例 — 将扩展配置文件添加到现有凭据：

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

更新命令接受的选项与 save 但所有选项都是可选的 — 只有您提供的字段才会更新。

凭据列表

查看当前保存的凭据（密码会被掩码）：

bunx @capgo/cli@latest build credentials list

# List credentials for a specific app
bunx @capgo/cli@latest build credentials list --appId com.example.app

清除凭据

从本地机器中删除保存的凭据：

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Clear credentials for a specific app + platform
bunx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios

迁移凭据

将遗留的单一配置文件格式转换为新的多目标格式：

bunx @capgo/cli@latest build credentials migrate --platform ios

迁移命令检测旧的 BUILD_PROVISION_PROFILE_BASE64 凭据，转换为 CAPGO_IOS_PROVISIONING_MAP,并移除遗留的键。请参见从单一配置文件迁移有关详细信息。

保存 iOS 凭据

完整示例

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

iOS 选项

选项	描述	必填
`--certificate <path>`	.p12证书文件路径	是（发布）
`--p12-password <password>`	p12证书密码	是 (发布)
`--ios-provisioning-profile <mapping>`	配置文件映射 (`bundleId=path`). 多目标应用程序可重复使用。如果只有一个配置文件且没有 bundleId 前缀，CLI 将自动从配置文件中推断。	是 (发布)
`--apple-key <path>`	API App Store Connect .p8 密钥路径	请参阅¹
`--apple-key-id <id>`	App Store Connect API 密钥 ID	请参阅¹
`--apple-issuer-id <id>`	App Store Connect API 发行者 ID (UUID)	请参阅¹
`--apple-team-id <id>`	App Store Connect 团队 ID	是
`--apple-id <email>`	Apple ID邮箱用于上传应用特定密码（替代API密钥）	查看注释²
`--apple-app-specific-password <password>`	应用特定密码（`xxxx-xxxx-xxxx-xxxx`)	查看注释²
`--apple-app-id <id>`	数字App Store Connect应用ID（例如 `1234567890`)	查看注释²
`--ios-distribution <mode>`	发布模式： `app_store` (默认)或 `ad_hoc`	无
`--output-upload`	启用Capgo下载链接（有效期限）	无（默认： `false`)
`--output-retention <seconds>`	保留构建输出的时间（例如 `3600s`)	否 (默认: `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	否

存储的内容

当您保存 iOS 凭据时，会将 CLI:

读取证书和配置文件
将它们转换为 base64 编码
保存到 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json 存储密码和 ID 为纯文本（仅限本地文件） --local)
存储的文件结构：

复制到剪贴板

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "CAPGO_IOS_PROVISIONING_MAP": "{\"com.example.app\":{\"profile\":\"...\",\"name\":\"match AppStore com.example.app\"}}",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456",
    "CAPGO_IOS_DISTRIBUTION": "app_store"
  }
}

保存 Android 凭据

完整示例

bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Android 选项

选项	描述	必填
`--keystore <path>`	keystore 或 jks 文件路径	是 (发布)
`--keystore-alias <alias>`	keystore 中的密钥别名	是 (发布)
`--keystore-key-password <password>`	密钥别名的密码	是 (发布)
`--keystore-store-password <password>`	keystore 的密码	是 (发布)
`--play-config <path>`	到 Play Store 服务账户 JSON 文件的路径	是 (提交)

存储的内容

当您保存 Android 凭据时，会将 CLI:

读取 keystore 和服务账户 JSON 文件
将它们转换为 base64 编码
保存到 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json 使用 --local)
仅本地文件存储密码和别名（以纯文本形式）

存储的文件结构：

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}

使用保存的凭据

您保存凭据后，它们将自动在您构建时使用：

# Credentials automatically loaded from ~/.capgo-credentials/credentials.json
bunx @capgo/cli@latest build request com.example.app --platform ios

您还可以使用环境变量覆盖保存的凭据：

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
bunx @capgo/cli@latest build request com.example.app --platform ios

优先顺序：

环境变量（最高优先级）
已保存的凭据 (~/.capgo-credentials/credentials.json, 或本地 .capgo-credentials.json)
没有凭据（优先级最低）

查看已保存的凭据

您保存的凭据列表：

bunx @capgo/cli@latest build credentials list

示例输出：

📋 Saved Build Credentials:

iOS Credentials:
  ✓ Certificate (base64)
  ✓ Provisioning Map (JSON)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android Credentials:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

Location: ~/.capgo-credentials/credentials.json

🔒 These credentials are stored locally on your machine only.
   When building, they are sent to Capgo but NEVER stored there.
   They are auto-deleted after build completion.

安全最佳实践

本地存储安全

文件权限

# Global credentials directory + file
chmod 700 ~/.capgo-credentials
chmod 600 ~/.capgo-credentials/credentials.json
# Local (per-project) credentials, if you use --local
chmod 600 .capgo-credentials.json

不要将凭证提交到仓库

# Ignore the per-project credentials file (used with --local)
echo ".capgo-credentials.json" >> .gitignore

全局文件位于你的家目录，外部仓库

分离凭证
- 本地开发和 CI/CD 使用不同的凭证
- 定期轮换凭证
- 不要将凭据共享给团队成员

CI/CD 使用

对于 CI/CD 环境， 优先使用环境变量 而不是保存凭据。

导出一个准备好的 `.env` (推荐)

而不是手动 base64 编码每个凭据文件（见下面， build credentials manage 为您生成文件:

bunx @capgo/cli@latest build credentials manage
# pick your app → choose "Export to .env"

它写入一个 .env.capgo.<appId>.<platform> 文件（权限 0600)，包含每个保存的凭据作为环境变量 — 每行是一个要添加到您的CI/CD提供者的机密。 --platform ios 两种平台默认组合; 添加 --platform android 或

环境变量参考手册

CLI读取以下环境变量以获取凭据：

iOS凭据：

变量	描述	格式	必填
`BUILD_CERTIFICATE_BASE64`	code用于签名的P12/PKCS12证书	Base64	是（发布）
`CAPGO_IOS_PROVISIONING_MAP`	JSON映射包ID到配置文件数据	JSON字符串	是（发布）
`P12_PASSWORD`	P12证书的密码	明文	可选
`APPLE_KEY_ID`	App Store Connect API Key ID	例如“ABC1234567”的字符串	请参见注释¹
`APPLE_ISSUER_ID`	App Store Connect API Issuer ID	UUID字符串	请参见注释¹
`APPLE_KEY_CONTENT`	App Store Connect API key (.p8文件内容)	Base64	查看注释¹
`APP_STORE_CONNECT_TEAM_ID`	Apple Developer Team ID	字符串（例如，“XXXXXXXXXX”）	是
`CAPGO_IOS_DISTRIBUTION`	分发模式： `app_store` (默认) 或 `ad_hoc`	字符串	否

Android 凭据：

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	__CAPGO_KEEP_0__文件用于签名APK/AAB	Base64	是 (发布)
`KEYSTORE_KEY_ALIAS`	__CAPGO_KEEP_0__文件中的密钥别名	字符串	是 (发布)
`KEYSTORE_KEY_PASSWORD`	__CAPGO_KEEP_0__文件中的密钥别名密码	明文	是*
`KEYSTORE_STORE_PASSWORD`	__CAPGO_KEEP_0__文件密码	普通文本	是
`PLAY_CONFIG_JSON`	Google Play 服务账户 JSON	Base64	是（提交）

*如果只提供一个密码，它将用于两个* KEYSTORE_KEY_PASSWORD 和 KEYSTORE_STORE_PASSWORD.

GitHub 动作示例

name: Cloud Build

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 @capgo/cli@latest build request com.example.app --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          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 @capgo/cli@latest build request com.example.app --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

准备 Base64 值

为了将您的凭据文件转换为 base64 以便于 CI/CD 秘密：

# iOS Certificate (.p12)
base64 -i certificate.p12 | tr -d '\n' > certificate_base64.txt

# iOS Provisioning Profiles — use the CLI to generate CAPGO_IOS_PROVISIONING_MAP:
bunx @capgo/cli@latest build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from ~/.capgo-credentials/credentials.json to your CI secrets

# iOS App Store Connect Key (.p8)
base64 -i AuthKey_XXXXXX.p8 | tr -d '\n' > apple_key_base64.txt

# Android Keystore (.keystore or .jks)
base64 -i release.keystore | tr -d '\n' > keystore_base64.txt

# Google Play Service Account JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

为什么环境变量更安全

这种方法更安全，因为：

秘密由您的 CI/CD 平台管理
无凭证文件在运行器
易于旋转和访问控制
凭证使用的审计追踪

凭证旋转

定期旋转您的凭证：

iOS: 每年生成新证书和API密钥
Android: 每年更改密钥库密码
团队成员变更后: 在团队成员离开时旋转

更新保存的凭据：

# Re-run save command with new credentials
bunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...

故障排除

”No credentials found”

如果构建提示找不到凭据：

检查是否保存了凭据:

bunx @capgo/cli@latest build credentials list

如果缺少凭据，请保存:

bunx @capgo/cli@latest build credentials save --platform ios ...

验证凭据文件存在:

ls -la ~/.capgo-credentials/credentials.json   # global
ls -la .capgo-credentials.json                 # local (--local)

读取凭据时出现“拒绝访问”错误

修复文件权限：

chmod 600 ~/.capgo-credentials/credentials.json   # global
chmod 600 .capgo-credentials.json                 # local

未使用凭据

检查是否正确指定了平台：

# Make sure --platform matches saved credentials
bunx @capgo/cli@latest build request com.example.app --platform ios  # Uses ios credentials
bunx @capgo/cli@latest build request com.example.app --platform android  # Uses android credentials

清除并重新保存凭据

如果凭据似乎被损坏：

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

从环境变量迁移

如果您当前正在使用环境变量，可以迁移到保存的凭据：

提取当前的环境变量

echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

解码base64文件恢复原始文件 (如需)

echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

使用CLI保存

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --p12-password "$P12_PASSWORD" \
  --apple-key-id "$APPLE_KEY_ID" \
  --apple-issuer-id "$APPLE_ISSUER_ID" \
  --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

如果您有保存在旧格式（单个 BUILD_PROVISION_PROFILE_BASE64）中的凭据，请运行：

bunx @capgo/cli@latest build credentials migrate --platform ios

将遗留的单一配置转换为 CAPGO_IOS_PROVISIONING_MAP 并删除旧的 BUILD_PROVISION_PROFILE_BASE64 和 APPLE_PROFILE_NAME 密钥。

测试构建

bunx @capgo/cli@latest build request com.example.app --platform ios

移除环境变量 (可选)

unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

文件位置

凭据存储在一个单独的 JSON 文件中：

全局 (默认): ~/.capgo-credentials/credentials.json — 在所有项目中共享
本地 (在 --local): .capgo-credentials.json 在项目根目录中 — 覆盖全局文件以便于该项目

文件在您第一次保存凭据时会自动创建。添加 .capgo-credentials.json 到您的 .gitignore 以便每个项目的凭据永远不会被提交。

下一步

开始 - 创建第一个构建
iOS构建 - iOS特定构建配置
Android构建 - Android特定构建配置
故障排除 - 常见问题和解决方案

需要帮助?

📚 [Troubleshooting guide](https://capgo.com/troubleshooting-guide)
💬 [Discord community](https://capgo.com/discord)
📧 Email: support@capgo.app

从管理凭证中继续

如果您正在使用 管理凭证 来规划CI/CD自动化，连接它到 Capgo CI/CD 为Capgo CI/CD中的产品工作流程 Capgo Native Builds 为产品工作流程中的Capgo原生构建 Capgo集成为产品工作流程中的Capgo集成 CI/CD集成 CI/CD集成的实现细节，以及 GitHub动作集成 for the implementation detail in GitHub Actions Integration.

凭据管理

概述

命令

交互式管理凭据

保存凭据

更新凭据

凭据列表

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS 选项

存储的内容

保存 Android 凭据

完整示例

Android 选项

存储的内容

使用保存的凭据

查看已保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

导出一个准备好的 .env (推荐)

环境变量参考手册

GitHub 动作示例

准备 Base64 值

为什么环境变量更安全

凭证旋转

故障排除

”No credentials found”

读取凭据时出现“拒绝访问”错误

未使用凭据

清除并重新保存凭据

从环境变量迁移

文件位置

下一步

需要帮助?

从管理凭证中继续

导出一个准备好的 `.env` (推荐)