管理凭据

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

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

概览

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（与您使用的相同的终端界面） build init 浏览存储的内容、查看每个应用和平台的配置、导出 CI/CD 准备好的文件或删除平台的凭据： .env 终端窗口

bunx @capgo/cli@latest build credentials manage

描述	选项
`--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]

这个 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

迁移凭据

将遗留的单-profile 格式转换为新的多目标格式：

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前缀，__CAPGO_KEEP_0__会自动从配置文件中推断。`bundleId=path`). Repeatable for multi-target apps. If only one profile and no bundleId prefix, CLI auto-infers from the profile.	App Store Connect __CAPGO_KEEP_0__ .p8密钥路径
`--apple-key <path>`	Path to App Store Connect API .p8 key	App Store Connect __CAPGO_KEEP_0__密钥ID
`--apple-key-id <id>`	App Store Connect API Key ID	Required
`--apple-issuer-id <id>`	App Store Connect API 发行者 ID (UUID)	See note¹
`--apple-team-id <id>`	App Store Connect Team ID	Yes
`--apple-id <email>`	App Store 专用 ID 电子邮件（替代 API 密钥）	See note²
`--apple-app-specific-password <password>`	App Store 专用密码（`xxxx-xxxx-xxxx-xxxx`)	See note²
`--apple-app-id <id>`	数字 App Store Connect 应用 ID（例如 `1234567890`)	See note²
`--ios-distribution <mode>`	发布模式： `app_store` (默认值) 或 `ad_hoc`	没有
`--output-upload`	为构建产物启用一个时间限制的Capgo下载链接	没有 (默认： `false`)
`--output-retention <seconds>`	保留构建输出的时间长度（例如 `3600s`)	没有 (默认： `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	没有

iOS应用程序凭证存储的内容

当您保存iOS凭证时，CLI:

读取证书和配置文件
将它们转换为base64编码
保存到 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json targetLanguage":"Simplified Chinese" --local)
protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"]

texts":["with","","","","","","","","",""],

{
  "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"
  }
}

The stored file structure:","Copy to clipboard","Saving Android Credentials","","Note","Note","Don’t have a keystore yet?","See the","Android Builds guide","for instructions on creating a keystore and setting up Play Store credentials."],

完整示例

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

存储的内容

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

环境变量参考文档

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

iOS 凭据：

变量	描述	格式	必填
`BUILD_CERTIFICATE_BASE64`	P12/PKCS12证书用于code签名	Base64	Yes (发布)
`CAPGO_IOS_PROVISIONING_MAP`	应用程序 ID 到配置文件数据的 JSON 映射	JSON 字符串	Yes (发布)
`P12_PASSWORD`	P12 证书的密码	明文	可选
`APPLE_KEY_ID`	App Store Connect API Key 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`	字符串	No

安卓凭证：

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	APK/AAB签名的keystore文件	Base64	是（发布）
`KEYSTORE_KEY_ALIAS`	keystore中的密钥别名	字符串	是（发布）
`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 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集成在CI/CD集成的实现细节中, GitHub 动作集成在GitHub 动作集成的实现细节中。

管理凭据

概览

命令

交互式管理凭据

保存凭据

更新凭据

列表凭据

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS选项

iOS应用程序凭证存储的内容

The stored file structure:","Copy to clipboard","Saving Android Credentials","","Note","Note","Don’t have a keystore yet?","See the","Android Builds guide","for instructions on creating a keystore and setting up Play Store credentials."],

完整示例

Android 选项

存储的内容

使用保存的凭据

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

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

环境变量参考文档

GitHub Actions 示例

准备 Base64 值

为什么环境变量更安全

凭证轮换

故障排除

没有找到凭据：

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

未使用的凭据

清除并重新保存凭据

迁移至环境变量

文件位置

下一步

需要帮助?

从管理凭证继续

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