管理凭据

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

方便地管理您的 iOS 和 Android 构建凭据，用于本地云构建。

概述

Capgo CLI 在您的机器上存储您的构建凭据 — 从未在 __CAPGO_KEEP_0__ 的服务器上。默认情况下，它们存储在一个 — 不会在Capgo的服务器上。它们默认存储在一个 文件中 , ~/.capgo-credentials/credentials.json用于所有项目共享。通过传递 --local 来保留它们 按项目 在 .capgo-credentials.json 取代。当您运行构建时，保存的凭据将自动使用并安全地发送到 Capgo，然后在构建完成后删除。

命令

交互式管理凭据

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

bunx @capgo/cli@latest build credentials manage

context	描述
`--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 它 命令使用 累积合并 --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

上下文：Capgo营销网站。角色：UI标签。见于：页面agents/[slug].astro。消息键`agents_page_copy_label`（Agents Page Copy Label）。

标题：清除凭据

# 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 密钥 ID	查看说明¹
`--apple-issuer-id <id>`	App Store Connect API 证书颁发者 ID (UUID)	查看说明¹
`--apple-team-id <id>`	App Store Connect 团队 ID	Yes
`--apple-id <email>`	Apple ID邮箱用于应用程序专用密码上传（替代API密钥）	请参见²
`--apple-app-specific-password <password>`	查看说明²`xxxx-xxxx-xxxx-xxxx`)	请参见²
`--apple-app-id <id>`	应用特定密码 ( `1234567890`)	请参见²
`--ios-distribution <mode>`	数字 App Store Connect 应用 ID (例如 `app_store` (默认) 或 `ad_hoc`	否
`--output-upload`	启用一个时间限制的Capgo下载链接用于构建输出	否 (默认:) `false`)
`--output-retention <seconds>`	构建输出保留多久（例如：) `3600s`)	否 (默认:) `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	否

标题：存储的内容

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

上下文：Capgo 营销网站。角色：UI 标签。见于：页面 agent/[slug].astro。消息键 `agents_page_copy_label` (Agents Page Copy Label)。

标题：Android 选项	选项	描述
`--keystore <path>`	必填	密钥库或 .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 context --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

context:Capgo营销网站.角色: UI标签.出现位置:页面代理/[slug].astro.消息键`agents_page_copy_label` (代理页面复制标签).

优先顺序：
环境变量（最高优先级）~/.capgo-credentials/credentials.json保存的凭据（ .capgo-credentials.json)
，或本地

无凭据（最低优先级）

标题：查看保存的凭据

bunx @capgo/cli@latest build credentials list

__CAPGO_KEEP_0__

📋 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> )包含所有保存的凭据作为环境变量 — 每行都是一个要添加到您的 CI/CD 提供商中的秘密。两种平台默认组合；添加 0600或 --platform ios （或 --platform android 为了将其范围限制在一个。

环境变量参考文档

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

iOS凭据：

变量	描述	格式	必填
`BUILD_CERTIFICATE_BASE64`	P12/PKCS12证书（用于code签名）	Base64	是（发布）
`CAPGO_IOS_PROVISIONING_MAP`	应用程序ID到配置文件数据的JSON映射	JSON字符串	是（发布）
`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”）	Yes
`CAPGO_IOS_DISTRIBUTION`	发布模式： `app_store` (默认) 或 `ad_hoc`	String	否

Android凭据:

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	APK/AAB签名的keystore文件	Base64	是（发布）
`KEYSTORE_KEY_ALIAS`	keystore中的密钥别名	String	是 (发布)
`KEYSTORE_KEY_PASSWORD`	密钥别名的密码	明文	是*
`KEYSTORE_STORE_PASSWORD`	密钥库文件的密码	明文	是*
`PLAY_CONFIG_JSON`	Google Play 服务账户 JSON	Base64	是 (提交)

*如果只提供一个密码，它将用于两个 KEYSTORE_KEY_PASSWORD 并且 KEYSTORE_STORE_PASSWORD.

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

为什么环境变量更安全

这种方法更安全，因为：

密钥由您的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 ...

Troubleshooting

页面区域: 支持/高级支持页面或底部支持部分。角色: 小节或页面标题。见于: 页面support-policy.astro。消息键`support_policy_troubleshooting_title` (Support Policy Troubleshooting Title)。

如果构建说没有找到凭据:

检查是否已保存凭据:

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

keys.

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 动作集成

管理凭据

概述

命令

交互式管理凭据

保存凭据

更新凭据

列表凭据

上下文：Capgo营销网站。角色：UI标签。见于：页面agents/[slug].astro。消息键`agents_page_copy_label`（Agents Page Copy Label）。

从本地机器中删除保存的凭据：

保存 iOS 凭据

完整示例

iOS选项

标题：存储的内容

保存 Android 凭证

完整示例

上下文：Capgo 营销网站。角色：UI 标签。见于：页面 agent/[slug].astro。消息键 `agents_page_copy_label` (Agents Page Copy Label)。

存储的内容

复制到剪贴板

无凭据（最低优先级）

安全最佳实践

本地存储安全

CI/CD 使用

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

环境变量参考文档

GitHub 操作示例

准备 Base64 值

为什么环境变量更安全

密钥轮换

Troubleshooting

页面区域: 支持/高级支持页面或底部支持部分。角色: 小节或页面标题。见于: 页面support-policy.astro。消息键`support_policy_troubleshooting_title` (Support Policy Troubleshooting Title)。

“读取凭证时出现“权限被拒绝”错误”

未使用的凭据

清除并重新保存凭据

从环境变量迁移

文件位置

下一步

需要帮助?

继续从管理凭据

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