管理凭据

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

在本地管理 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（与使用的相同） build init 浏览存储的内容，查看每个应用程序和平台的配置，导出一个 CI/CD-ready 文件，或者删除一个平台的凭据： .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=path`）可重复使用，适用于多目标应用。如果只有一个配置文件且没有bundleId前缀，CLI会自动从配置文件中推断。	是 (发布)
`--apple-key <path>`	App Store Connect API .p8密钥路径	请参见注释¹
`--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>`	用于上传 API 密钥的苹果 ID 邮箱（替代方案）	查看注释²
`--apple-app-specific-password <password>`	App Store Connect 应用程序特定密码（`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 Key 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	String (e.g., “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 私钥
安卓每年更改密钥库密码
团队成员变更后当团队成员离开时，需要旋转

更新保存的凭据：

# 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 测试构建

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` (推荐)