凭据管理

__CAPGO_KEEP_11__

简介

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 uses) 的界面，允许您浏览存储的内容、查看每个应用和平台的配置、导出 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]

The update __CAPGO_KEEP_0__ 使用的加性合并 --overwrite-ios-provisioning-map.

用于配置文件 — 新配置文件与现有配置文件进行合并。要替换整个配置映射而不是，请添加

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

__CAPGO_KEEP_0__ 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 凭据

保存 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)	是 (发布)
`--p12-password <password>`	证书文件密码	是 (发布)
`--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__ Key ID
`--apple-key-id <id>`	App Store Connect API Key ID	Note: The .p8 key must be uploaded to App Store Connect before generating the 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 下载链接用于构建 artifact	否 (默认值： `false`)
`--output-retention <seconds>`	保留构建输出的时间长度（例如 `3600s`)	否 (默认值： `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	否

标题：什么被存储

When you save iOS credentials, the CLI:

将它们转换为 base64 编码
保存到
(或 ~/.capgo-credentials/credentials.json 存储密码和 ID 为纯文本（仅限本地文件） .capgo-credentials.json Ad-Hoc 分发模式 --local)
什么被存储

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

保存 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>`	密钥别名密码	Yes (release)
`--keystore-store-password <password>`	密码库的密码	Yes (release)
`--play-config <path>`	Play Store 服务账户 JSON 文件路径	Yes (submission)

存储的内容

当您保存 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 来将其限制到一个。

环境变量参考

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

iOS凭据：

变量	描述	格式	是否必填
`BUILD_CERTIFICATE_BASE64`	P12/PKCS12证书用于code签名	Base64	Yes (release)
`CAPGO_IOS_PROVISIONING_MAP`	__CAPGO_KEEP_0__	JSON string	Yes (release)
`P12_PASSWORD`	__CAPGO_KEEP_0__	Plain text	Optional
`APPLE_KEY_ID`	App Store Connect API Key ID	String (例如，“ABC1234567”)	See note¹
`APPLE_ISSUER_ID`	App Store Connect API Issuer ID	UUID string	见注¹
`APPLE_KEY_CONTENT`	App Store Connect API key (.p8 文件内容)	Base64	见注¹
`APP_STORE_CONNECT_TEAM_ID`	Apple Developer Team ID	String（例如，“XXXXXXXXXX”）	是
`CAPGO_IOS_DISTRIBUTION`	发布模式： `app_store` (默认) 或 `ad_hoc`	String	否

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 示例

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：每年更改密钥库密码
团队成员变动后: 团队成员离开时旋转

更新保存的凭据：

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

故障排除

”No credentials found”

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

检查是否保存了凭据:

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), run:

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 to your .gitignore so per-project credentials are never committed.

Next Steps

Getting Started - Create your first build
iOS Builds - iOS-specific build configuration
Android Builds - Android-specific build configuration
Troubleshooting - Common issues and solutions

需要帮助？

从管理凭证中继续

如果您正在使用 管理凭证 来规划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.

凭据管理

简介

命令

交互式管理凭据

保存凭据

更新凭据

列表凭据

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS选项

标题：什么被存储

保存 Android 凭证

完整示例

Android 选项

存储的内容

使用保存的凭据

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD使用

导出一个 .env （推荐）

环境变量参考

GitHub Actions 示例

准备Base64值

为什么环境变量更安全

凭证轮换

故障排除

”No credentials found”

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

凭证未被使用

清除并重新保存凭证

从环境变量迁移

文件位置

Next Steps

需要帮助？

从管理凭证中继续

导出一个 `.env` （推荐）