管理凭据

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示。

Manage your iOS and Android build credentials locally for convenient cloud builds.

Overview

Capgo CLI 在您的机器上存储您的构建凭证 — 从不在__CAPGO_KEEP_0__的服务器上。通过默认方式，它们存储在一个 — never on Capgo’s servers. By default they live in one 文件中， 所有项目共享。 ~/.capgo-credentials/credentials.json传递 --local 保留它们 按项目 在 .capgo-credentials.json 在构建时，保存的凭据会自动使用并安全地发送到Capgo,然后在构建完成后删除。

命令

交互式管理凭据

使用交互式管理器来快速处理保存的凭据。它打开一个 TUI（与您使用的相同的终端界面），您可以浏览存储的内容、查看每个应用和平台的配置、导出 CI/CD-ready 文件或删除平台的凭据： build init 终端窗口 .env 复制到剪贴板

bunx @capgo/cli@latest build credentials manage

Manage Credentials Interactively	Manage Credentials Interactively
`--appId <appId>`	App to manage (prompts you to pick if omitted)
`--platform <ios\|android>`	平台管理 (如果省略则会提示选择)
`--local`	Use the per-project `.capgo-credentials.json` 而不是全局文件

Prefer one-shot, scriptable commands? Use the individual commands below.

保存凭据

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

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

更新凭据

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

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

The update 命令使用 累积合并 用于配置文件 — 新配置文件与现有配置文件合并。要替换整个配置映射而不是，请添加 --overwrite-ios-provisioning-map.

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

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

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

List Credentials

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

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 选项

选项	描述	Required
`--certificate <path>`	.p12证书文件路径	Yes (release)
`--p12-password <password>`	.p12证书密码	Yes (release)
`--ios-provisioning-profile <mapping>`	配置文件映射（`bundleId=path`）. 可重复使用于多目标应用程序。如果只有一个配置文件且没有bundleId前缀，CLI会自动从配置文件中推断。	Yes (release)
`--apple-key <path>`	App Store Connect API .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 Team ID	是
`--apple-id <email>`	用于上传 app 专用密码的 Apple ID 邮箱（替代 API 密钥）	见注释²
`--apple-app-specific-password <password>`	专用密码（`xxxx-xxxx-xxxx-xxxx`)	见注释²
`--apple-app-id <id>`	数字 App Store Connect app ID（例如 `1234567890`)	见注释²
`--ios-distribution <mode>`	发布模式： `app_store` (默认) 或 `ad_hoc`	否
`--output-upload`	为构建产物启用一个时间限制的Capgo下载链接	否 (默认： `false`)
`--output-retention <seconds>`	保留构建输出的时间长度（例如： `3600s`)	否 (默认： `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	¹ App Store Connect __CAPGO_KEEP_0__ Key Requirements

将它们转换为 base64 编码

When you save iOS credentials, the CLI:

What Gets Stored
Section titled “What Gets Stored”
When you save iOS credentials, the __CAPGO_KEEP_0__: ~/.capgo-credentials/credentials.json Reads the certificate and provisioning profile files .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 中的密钥别名	Yes (release)
`--keystore-key-password <password>`	密钥别名的密码	Yes (release)
`--keystore-store-password <password>`	keystore的密码	Yes (release)
`--play-config <path>`	Play Store服务账户 JSON 的路径	Yes (submission)

存储的内容

当您保存 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

The global file lives in your home directory, outside the repository.

分离凭证
- 本地开发和 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> )，包含所有保存的凭据作为环境变量 — 每行都是要添加到你的 CI/CD 提供商中的一个秘密。两种平台都默认组合；添加 0600或 --platform ios 来将其限制到一个平台 --platform android __CAPGO_KEEP_0__

环境变量参考文档

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

iOS 凭据：

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

安卓凭证:

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	APK/AAB签名的keystore文件	Base64	是（发布）
`KEYSTORE_KEY_ALIAS`	keystore中的密钥别名	字符串	是（发布）
`KEYSTORE_KEY_PASSWORD`	密钥别名的密码	明文	是*
`KEYSTORE_STORE_PASSWORD`	密钥库文件的密码	明文	是*
`PLAY_CONFIG_JSON`	Google Play 服务帐号 JSON	Base64	是 (提交)

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

GitHub Actions 示例

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

: 每年生成新证书和__CAPGO_KEEP_0__密钥Regularly rotate your credentials on iOS: Generate new certificates and API keys yearly
Android: 每年更改keystore密码
团队成员变更后: 团队成员离职时旋转

更新保存的凭据：

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

故障排除

“未找到凭据”

如果构建显示未找到凭据：

检查是否已保存凭据:

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 ...

Migrate from Environment Variables

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

提取当前的环境变量

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特定的构建配置
故障排除 - 常见问题和解决方案

需要帮助?

📚 故障排除指南
💬 Discord 社区
📧 电子邮件：支持@capgo.app

从管理凭证继续

如果您正在使用 管理凭证 为 CI/CD 自动化编排做好准备，连接它 Capgo CI/CD 在 Capgo CI/CD 中配置产品工作流程 Capgo 原生构建在 Capgo 原生构建中配置产品工作流程 Capgo 集成在 Capgo 集成中配置产品工作流程 CI/CD 集成在 CI/CD 集成的实现细节中 GitHub 动作集成在 GitHub 动作集成的实现细节中

管理凭据

Overview

命令

交互式管理凭据

保存凭据

更新凭据

List Credentials

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS 选项

将它们转换为 base64 编码

标题：保存Android凭据

完整示例

Android 选项

存储的内容

使用保存的凭据

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

导出一个可用的 .env (推荐)

环境变量参考文档

GitHub Actions 示例

准备 Base64 值

为什么环境变量更安全

凭证轮换

故障排除

“未找到凭据”

读取凭据时出现“权限被拒绝”

未使用的凭证

清除并重新保存凭证

Migrate from Environment Variables

文件位置

下一步

需要帮助?

从管理凭证继续

导出一个可用的 `.env` (推荐)