管理凭据

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

管理您的iOS和Android构建凭据，方便地在云端进行构建。

概述

Capgo CLI存储您的构建凭据 在您的机器上 — 从不在Capgo的服务器上。默认情况下，它们存储在一个全局文件 ~/.capgo-credentials/credentials.json, --local 所有项目共享。通过 来保留它们 按项目进行管理 .capgo-credentials.json 在构建时，保存的凭据将自动使用并安全地发送到 Capgo，然后在构建完成后删除。

命令

交互式管理凭据

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

bunx @capgo/cli@latest build credentials manage

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

使用一次性脚本命令? 请使用以下单个命令

保存凭据

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

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 更新命令接受同样的选项作为

凭据列表

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

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>`	证书文件密码	是 (发布)
`--ios-provisioning-profile <mapping>`	配置文件映射 (`bundleId=path`支持多目标应用重复使用。如果只有一个配置文件且没有 bundleId 前缀,CLI 会自动从配置文件中推断。	是 (发布)
`--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 团队 ID	Yes
`--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`	跳过自动构建编号递增	否

When you save iOS credentials, the __CAPGO_KEEP_0__:

当您保存 iOS 凭据时，CLI：

Saves them to
(or
在保存 iOS 凭证时，__CAPGO_KEEP_0__将执行以下操作： ~/.capgo-credentials/credentials.json 读取证书和分发配置文件 .capgo-credentials.json 与 --local)
仅限本地文件存储密码和 ID，未加密

存储的文件结构：

{
  "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-key-password <password>`	密钥别名的密码	是 (发布)
`--keystore-store-password <password>`	密钥库的密码	是 (发布)
`--play-config <path>`	Play Store 服务账户 JSON 文件的路径	是 (提交)

存储的内容

当您保存 Android 凭据时，CLI:

读取密钥库和服务账户 JSON 文件
将它们转换为 base64 编码
保存到 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json context --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

在您的家目录（home directory）中，repo外面存放着全局文件。

分离凭据
- 在本地开发和 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 导出一个可用的 .env 文件（推荐）

环境变量参考文档

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

iOS凭据：

变量	描述	格式	必填
`BUILD_CERTIFICATE_BASE64`	P12/PKCS12证书用于code签名	Base64	是（发布）
`CAPGO_IOS_PROVISIONING_MAP`	bundle ID到配置文件数据的JSON映射	JSON字符串	是（发布）
`P12_PASSWORD`	P12证书的密码	纯文本	可选
`APPLE_KEY_ID`	App Store Connect 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: 每年生成新证书和API密钥
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 ...

从环境变量迁移

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

提取您的当前环境变量

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 社区
📧 电子邮件: support@capgo.app

继续从管理凭证

如果您正在使用 管理凭证 为 CI/CD 自动化规划,连接它 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建为产品工作流程在 Capgo 原生构建中 Capgo 集成为产品工作流程在 Capgo 集成中 CI/CD 集成为产品工作流程在 Capgo Builder / 原生云构建产品页面中 GitHub 行为集成 GitHub 动作集成

管理凭据

概述

命令

交互式管理凭据

保存凭据

更新凭据

凭据列表

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS选项

When you save iOS credentials, the __CAPGO_KEEP_0__:

保存 Android 凭据

完整示例

Android 选项

存储的内容

复制到剪贴板

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

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

环境变量参考文档

GitHub Actions 示例

准备Base64值

为什么环境变量更安全

凭证轮换

故障排除

没有找到凭据

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

未使用的凭据

清除并重新保存凭据

从环境变量迁移

文件位置

下一步

需要帮助?

继续从管理凭证

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