凭据管理

在本地管理 iOS 和 Android 构建凭证以便于云构建。

概述

Capgo CLI 在您的机器上存储您的构建凭据 而不是在__CAPGO_KEEP_0__的服务器上。默认情况下，凭据存储在一个 — never on Capgo’s servers. By default they live in one 文件中， 所有项目共享。您可以 ~/.capgo-credentials/credentials.json将它们 --local 按项目 存储 。当您运行构建时，保存的凭据会自动使用并安全地发送到__CAPGO_KEEP_0__，然后在构建完成后删除。 .capgo-credentials.json instead. When you run a build, the saved credentials are used automatically and sent securely to Capgo, then deleted after the build completes.

需要帮助获取凭证吗？

如果您尚未获得证书和凭证，请查看这些全面指南：

iOS：

• 如何获取iOS证书 - 步骤指南
• iOS证书指南 -详细的步骤指南
• 博客：自动iOS构建 - 完整的CI/CD设置

Android：

• 创建一个Keystore - 步骤指南
• Android 证书指南 - 细节的步骤指南
• 博客：自动 Android 构建 - 完整的 CI/CD 设置

安全保证

您的凭据永远不会在Capgo服务器上永久存储：

• ✅仅在活动构建过程中使用
• ✅在构建完成后自动删除
• ✅最大保留时间：24小时（即使构建失败）
• ✅应用程序直接发送到 App Store/Play Store - 我们存储 NOTHING
• ✅ 使用 HTTPS 安全传输

命令

交互式管理凭据

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

bunx @capgo/cli@latest build credentials manage

Manage Credentials Interactively	The quickest way to work with your saved credentials is the interactive manager. It opens a TUI (the same one you use) where you can browse what’s stored, see what’s configured per app and platform, export a CI/CD-ready file, or delete a platform’s credentials:
--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 凭据

注意

Saving iOS Credentials

还没有iOS证书吗？ 查看 iOS Builds指南 了解如何创建证书和配置文件的说明。

完整示例

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)	是 (发布)
--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 Key ID	请参见注释¹
--apple-issuer-id <id>	App Store Connect API 发行者 ID (UUID)	查看注释¹
--apple-team-id <id>	App Store Connect 团队 ID	是
--ios-distribution <mode>	发布模式： app_store (默认) 或 ad_hoc	否
--output-upload	启用一个时间限制的 Capgo 下载链接用于构建产物	否 (默认： false)
--output-retention <seconds>	保留构建输出的时间长度（例如 3600s)	否 (默认： 3600s)
--skip-build-number-bump	跳过自动构建编号递增	否

¹ App Store Connect API Key Requirements

• app_store 模式 (默认): 三个API密钥选项都需要 除非您传递 或 --output-upload (这可以避免使用__CAPGO_KEEP_0__驱动的提交) --skip-build-number-bump (which bypass the need for API-driven submission).
• ad_hoc : 这些选项不需要mode (default): All three __CAPGO_KEEP_0__ key options are — 无 App Store 提交发生。请参阅 Ad-Hoc 分发模式 存储的内容

标题：存储的内容

When you save iOS credentials, the CLI:

1. 将它们转换为 base64 编码
2. 将它们保存到
3. (或 ~/.capgo-credentials/credentials.json 以 .capgo-credentials.json 以纯文本存储密码和 ID（仅限本地文件） --local)
4. 本地文件

The stored file structure：

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

Saving Android Credentials

注意

没有keystore吗？ 查看 Android Builds指南 为创建keystore和设置Play Store凭据提供了说明。

Complete Example

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 中的密钥别名	是（发布）
--keystore-key-password <password>	密钥别名的密码	Yes (release)
--keystore-store-password <password>	__CAPGO_KEEP_0__（密钥库密码）	Yes (release)
--play-config <path>	__CAPGO_KEEP_1__（Play Store服务账户JSON路径）	Yes (submission)

存储的内容

当您保存 Android 凭证时，会将 CLI:

1. 读取密钥库和服务账户 JSON 文件
2. 将它们转换为 base64 编码
3. 将它们保存到 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json targetLanguage":"Simplified Chinese" --local)
4. protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"]

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

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}

"The stored file structure：","","","","","","","",""

"Section titled “使用保存的凭据”"

# 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

优先顺序：

1. 环境变量（最高优先级）
2. 保存的凭据（~/.capgo-credentials/credentials.json，或本地 .capgo-credentials.json)
3. 没有凭据（最低优先级）

查看保存的凭据

列出您保存的凭据：

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.

安全最佳实践

本地存储安全

1. 文件权限

   # 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

2. 不要提交凭证

   # Ignore the per-project credentials file (used with --local)
   echo ".capgo-credentials.json" >> .gitignore

   全局文件位于你的家目录，位于仓库之外。

3. 分离凭证

   • 建议为本地开发和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 来将其限制到一个平台。

注意

导出的文件包含您的签名密钥 — 将其添加到 .gitignore 并且不要将其提交。

环境变量参考文档

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

iOS凭据：

变量	描述	格式	是否必填
BUILD_CERTIFICATE_BASE64	用于code签名的P12/PKCS12证书	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 Issuer 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 __CAPGO_KEEP_0__ Actions 示例 KEYSTORE_STORE_PASSWORD.

标题为“GitHub Actions 示例”的部分

github

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

提示

它 tr -d '\n' 去除换行符以创建一个单行Base64字符串，这样更容易作为CI/CD密钥存储。

为什么环境变量更安全

This approach is more secure because:

• 您的 CI/CD 平台管理机密
• 无需在运行器上存储凭据
• 易于轮换和访问控制
• 对机密使用的审计跟踪

凭据轮换

定期轮换您的凭据：

1. iOS: 每年生成新证书和 API 密钥
2. Android: 每年更改密钥库密码
3. 团队成员变动后: 当团队成员离开时旋转

更新保存的凭据：

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

故障排除

”No credentials found”

如果构建提示找不到凭据：

1. 检查是否保存了凭据:

   bunx @capgo/cli@latest build credentials list

2. 如果缺失则保存凭据:

   bunx @capgo/cli@latest build credentials save --platform ios ...

3. 验证凭据文件是否存在:

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

从环境变量迁移

如果您目前正在使用环境变量，

1. 提取当前环境变量

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. 解码base64文件恢复原始文件 (如需)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. 使用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 键。

4. 测试构建

   bunx @capgo/cli@latest build request com.example.app --platform ios

5. 移除环境变量 (可选)

   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 动作集成 for the implementation detail in GitHub Actions Integration.