管理凭证

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

在本地管理 iOS 和 Android 构建凭据，方便云端构建。

概述

Capgo CLI 在您的机器上存储您的构建凭据 — 从不在 __CAPGO_KEEP_0__ 的服务器上。默认情况下，它们存储在一个 — never on Capgo’s servers. By default they live in one 文件中 , ~/.capgo-credentials/credentials.json所有项目共享。 --local 继续保留它们 每个项目 in .capgo-credentials.json 否则。当您运行构建时，保存的凭据将自动使用并安全地发送到 Capgo，然后在构建完成后删除。

命令

交互式管理凭据

使用交互式管理器可以快速管理您的保存的凭据。它打开一个 TUI（与使用的相同的）界面，允许您浏览存储的内容，查看每个应用程序和平台的配置，导出一个 CI/CD-ready 文件，或者删除一个平台的凭据： build init 终端窗口 .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

迁移凭据

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

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前缀，__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	¹请参见[此处](https://capgo.io/docs/builder/credentials/#note-1)
`--apple-key-id <id>`	App Store Connect API Key ID	查看注释¹
`--apple-issuer-id <id>`	App Store Connect API Issuer ID (UUID)	查看注释¹
`--apple-team-id <id>`	App Store Connect Team ID	是
`--apple-id <email>`	用于应用特定密码上传的苹果 ID 邮箱（替代 API 密钥）	查看注释²
`--apple-app-specific-password <password>`	应用特定密码（`xxxx-xxxx-xxxx-xxxx`)	查看注释²
`--apple-app-id <id>`	数字 App Store Connect 应用 ID（例如 `1234567890`)	查看注释²
`--ios-distribution <mode>`	Distribution mode: `app_store` (default) 或 `ad_hoc`	No
`--output-upload`	启用一个时间限制的Capgo下载链接	No (default: `false`)
`--output-retention <seconds>`	保留构建输出的时间（例如 `3600s`)	No (default: `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	No

存储的内容

当你保存 iOS 凭据时，CLI:

读取证书和配置文件
将它们转换为 base64 编码
保存到 ~/.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 与” --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`	应用 ID 到配置文件数据的 JSON 映射	JSON 字符串	是 (发布)
`P12_PASSWORD`	P12 证书的密码	纯文本	非必填
`APPLE_KEY_ID`	API App Store Connect 密钥 ID	String (e.g., “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 凭据:

变量	描述	格式	必填
`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 Example

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值

终端窗口

# 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 context:Capgo营销网站。角色：短UI标签或导航项。见于：页面trust.astro。消息键`and`（And）。

测试构建

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特定的构建配置
安卓构建 - 安卓特定构建配置
故障排除上下文:支持/高级支持页面或底部支持部分。角色:部分或页面标题。见于:页面support-policy.astro。消息键`support_policy_troubleshooting_title` (支持政策故障排除标题)

- 常见问题和解决方案

support@__CAPGO_KEEP_0__.app

如果您正在使用 管理凭据 规划CI/CD自动化,连接它与 Capgo CI/CD 为Capgo CI/CD产品工作流程 Capgo 原生构建为Capgo 原生构建产品工作流程 Capgo 集成为Capgo 集成产品工作流程 CI/CD集成为CI/CD集成的实现细节,并 GitHub 动作集成为GitHub Actions Integration的实现细节。

管理凭证

概述

命令

交互式管理凭据

保存凭据

更新凭证

列表凭据

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS选项

存储的内容

保存 Android 凭据

完整示例

Android 选项

存储的内容

使用保存的凭据

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

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

环境变量参考文档

GitHub Actions Example

准备Base64值

为什么环境变量更安全

凭据轮换

故障排除

找不到凭据

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

凭证未被使用

清除并重新保存凭证

从环境变量迁移

文件位置

下一步

- 常见问题和解决方案

support@__CAPGO_KEEP_0__.app

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