Back to Details

doppler-secret-validation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Doppler Secret Validation

Doppler密钥验证

Overview

概述

Workflow for securely adding, validating, and testing API tokens and credentials in Doppler secrets management.
在Doppler密钥管理中安全添加、验证和测试API令牌与凭证的工作流。

When to Use This Skill

何时使用此Skill

Use this skill when:
  • User provides API tokens or credentials (PyPI, GitHub, AWS, etc.)
  • User mentions "add to Doppler", "store secret", "validate token"
  • User wants to test authentication before production use
  • User needs to verify secret storage and retrieval
在以下场景使用此Skill：
  • 用户提供API令牌或凭证（PyPI、GitHub、AWS等）
  • 用户提及“添加至Doppler”、“存储密钥”、“验证令牌”
  • 用户希望在生产环境使用前测试认证
  • 用户需要验证密钥的存储与检索

Workflow

工作流

Step 1: Test Token Format (Before Adding to Doppler)

步骤1：测试令牌格式（添加至Doppler前）

Before storing in Doppler, validate token format:
bash
undefined
在存储到Doppler之前，先验证令牌格式：
bash
undefined

Check token format, length, prefix

Check token format, length, prefix

python3 -c "token = 'TOKEN_VALUE'; print(f'Prefix: {token[:20]}...'); print(f'Length: {len(token)}')"

**Common token formats**:

- PyPI: `pypi-...` (179 chars)
- GitHub: `ghp_...` (40+ chars)
- AWS: 20-char access key + 40-char secret
python3 -c "token = 'TOKEN_VALUE'; print(f'Prefix: {token[:20]}...'); print(f'Length: {len(token)}')"

**常见令牌格式**：

- PyPI: `pypi-...`（179字符）
- GitHub: `ghp_...`（40+字符）
- AWS: 20字符访问密钥 + 40字符密钥

Step 2: Add Secret to Doppler

步骤2：将密钥添加至Doppler

bash
doppler secrets set SECRET_NAME="value" --project PROJECT --config CONFIG
Example:
bash
doppler secrets set PYPI_TOKEN="pypi-AgEI..." \
  --project claude-config --config prd
Important: CLI doesn't support 
--note
. Add notes via dashboard:
  1. https://dashboard.doppler.com
  2. Navigate: PROJECT → CONFIG → SECRET_NAME
  3. Edit → Add descriptive note
bash
doppler secrets set SECRET_NAME="value" --project PROJECT --config CONFIG
示例：
bash
doppler secrets set PYPI_TOKEN="pypi-AgEI..." \
  --project claude-config --config prd
重要提示：CLI不支持
--note
参数。请通过控制台添加备注：
  1. https://dashboard.doppler.com
  2. 导航至：项目 → 配置 → 密钥名称
  3. 编辑 → 添加描述性备注

Step 3: Validate Storage

步骤3：验证存储

Use the bundled validation script:
bash
/usr/bin/env bash << 'VALIDATE_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/doppler-secret-validation
uv run scripts/validate_secret.py \
  --project PROJECT \
  --config CONFIG \
  --secret SECRET_NAME
VALIDATE_EOF
This validates:
  1. Secret exists in Doppler
  2. Secret retrieval works
  3. Environment injection works via 
    doppler run
Example:
bash
uv run scripts/validate_secret.py \
  --project claude-config \
  --config prd \
  --secret PYPI_TOKEN
使用内置的验证脚本：
bash
/usr/bin/env bash << 'VALIDATE_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/doppler-secret-validation
uv run scripts/validate_secret.py \
  --project PROJECT \
  --config CONFIG \
  --secret SECRET_NAME
VALIDATE_EOF
该脚本会验证以下内容：
  1. 密钥是否存在于Doppler中
  2. 密钥检索是否正常
  3. 通过
    doppler run
    进行环境变量注入是否正常
示例：
bash
uv run scripts/validate_secret.py \
  --project claude-config \
  --config prd \
  --secret PYPI_TOKEN

Step 4: Test API Authentication

步骤4：测试API认证

Use the bundled auth test script (adapt test_api_authentication() for specific API):
bash
/usr/bin/env bash << 'CONFIG_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/doppler-secret-validation
doppler run --project PROJECT --config CONFIG -- \
  uv run scripts/test_api_auth.py \
    --secret SECRET_NAME \
    --api-url API_ENDPOINT
CONFIG_EOF
Example (PyPI):
bash
doppler run --project claude-config --config prd -- \
  uv run scripts/test_api_auth.py \
    --secret PYPI_TOKEN \
    --api-url https://upload.pypi.org/legacy/
使用内置的认证测试脚本（根据具体API调整test_api_authentication()函数）：
bash
/usr/bin/env bash << 'CONFIG_EOF'
cd ${CLAUDE_PLUGIN_ROOT}/skills/doppler-secret-validation
doppler run --project PROJECT --config CONFIG -- \
  uv run scripts/test_api_auth.py \
    --secret SECRET_NAME \
    --api-url API_ENDPOINT
CONFIG_EOF
示例（PyPI）：
bash
doppler run --project claude-config --config prd -- \
  uv run scripts/test_api_auth.py \
    --secret PYPI_TOKEN \
    --api-url https://upload.pypi.org/legacy/

Step 5: Document Usage

步骤5：记录使用方式

After validation, document the usage pattern for the user:
bash
/usr/bin/env bash << 'CONFIG_EOF_2'
验证完成后，为用户记录使用模式：
bash
/usr/bin/env bash << 'CONFIG_EOF_2'

Pattern 1: Doppler run (recommended for CI/scripts)

模式1：Doppler run（推荐用于CI/脚本）

doppler run --project PROJECT --config CONFIG -- COMMAND
doppler run --project PROJECT --config CONFIG -- COMMAND

Pattern 2: Manual export (for troubleshooting)

模式2：手动导出（用于故障排查）

export SECRET_NAME=$(doppler secrets get SECRET_NAME
--project PROJECT --config CONFIG --plain) CONFIG_EOF_2
undefined
export SECRET_NAME=$(doppler secrets get SECRET_NAME
--project PROJECT --config CONFIG --plain) CONFIG_EOF_2
undefined

Step 5b: mise [env] Integration (Recommended for Local Development)

步骤5b：mise [env] 集成（推荐用于本地开发）

For multi-account GitHub setups or per-directory credential needs, integrate Doppler secrets with mise 
[env]
:
toml
undefined
针对多账号GitHub配置或按目录划分的凭证需求，将Doppler密钥与mise 
[env]
集成：
toml
undefined

.mise.toml

.mise.toml

[env]
[env]

Option A: Direct Doppler CLI fetch (slower, always fresh)

选项A：直接通过Doppler CLI获取（速度较慢，始终获取最新值）

GH_TOKEN = "{{ exec(command='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}" GITHUB_TOKEN = "{{ exec(command='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}"
GH_TOKEN = "{{ exec(command='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}" GITHUB_TOKEN = "{{ exec(command='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}"

Option B: Cache for performance (1 hour cache)

选项B：缓存以提升性能（缓存1小时）

GH_TOKEN = "{{ cache(key='gh_token', duration='1h', run='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}" GITHUB_TOKEN = "{{ cache(key='gh_token', duration='1h', run='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}"

**Note**: Set BOTH `GH_TOKEN` and `GITHUB_TOKEN` - different tools check different variable names (gh CLI vs npm scripts).

**Why mise [env]?** Doppler `doppler run` is session-scoped; mise `[env]` provides directory-scoped credentials that persist across commands.

See [`mise-configuration` skill](../../../itp/skills/mise-configuration/SKILL.md#github-token-multi-account-patterns) for complete patterns.
GH_TOKEN = "{{ cache(key='gh_token', duration='1h', run='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}" GITHUB_TOKEN = "{{ cache(key='gh_token', duration='1h', run='doppler secrets get GH_TOKEN --project myproject --config prd --plain') }}"

**注意**：同时设置`GH_TOKEN`和`GITHUB_TOKEN`——不同工具会检查不同的变量名（gh CLI vs npm脚本）。

**为什么选择mise [env]？** Doppler的`doppler run`是会话级别的；而mise `[env]`提供的是目录级别的凭证，可跨命令持久化。

查看[`mise-configuration` Skill](../../../itp/skills/mise-configuration/SKILL.md#github-token-multi-account-patterns)获取完整模式。

Common Patterns

常见模式

Multiple Configs (dev, stg, prd)

多配置环境（dev、stg、prd）

Add secret to multiple environments:
bash
undefined
将密钥添加至多个环境：
bash
undefined

Production

生产环境

doppler secrets set TOKEN="prod-value" --project foo --config prd
doppler secrets set TOKEN="prod-value" --project foo --config prd

Development

开发环境

doppler secrets set TOKEN="dev-value" --project foo --config dev
undefined
doppler secrets set TOKEN="dev-value" --project foo --config dev
undefined

Verify Secret Across Configs

跨配置验证密钥

bash
/usr/bin/env bash << 'CONFIG_EOF_3'
for config in dev stg prd; do
  echo "=== $config ==="
  doppler secrets get TOKEN --project foo --config $config --plain | head -c 20
  echo "..."
done
CONFIG_EOF_3
bash
/usr/bin/env bash << 'CONFIG_EOF_3'
for config in dev stg prd; do
  echo "=== $config ==="
  doppler secrets get TOKEN --project foo --config $config --plain | head -c 20
  echo "..."
done
CONFIG_EOF_3

Security Guidelines

安全指南

  1. Never log full secrets: Use 
    ${SECRET:0:20}...
    masking
  2. Prefer doppler run: Scopes secrets to single command
  3. Use --plain only for piping: Human-readable view masks secrets
  4. Separate configs per environment: dev/stg/prd isolation
  1. 切勿记录完整密钥：使用
    ${SECRET:0:20}...
    进行掩码处理
  2. 优先使用doppler run：将密钥作用范围限定于单个命令
  3. 仅在管道传输时使用--plain：人类可读视图会自动掩码密钥
  4. 按环境分离配置：dev/stg/prd环境隔离

Bundled Resources

内置资源

  • scripts/validate_secret.py - Complete validation suite (existence, retrieval, injection)
  • scripts/test_api_auth.py - Template for API authentication testing
  • references/doppler-patterns.md - Common CLI patterns and examples
  • scripts/validate_secret.py - 完整验证套件（存在性、检索、注入）
  • scripts/test_api_auth.py - API认证测试模板
  • references/doppler-patterns.md - 常见CLI模式与示例

Reference

参考资料

Troubleshooting

故障排查

IssueCauseSolution
Secret not foundWrong project/config specifiedVerify with 
doppler secrets ls --project X --config
Auth test fails with 401Token expired or invalidRegenerate token, re-add to Doppler
doppler run hangsCLI waiting for inputAdd 
--no-interactive
flag
Token prefix mismatchWrong token type usedCheck expected format (pypi-, ghp-, AKIA, etc.)
Validation script not foundWrong directory contextEnsure CLAUDE_PLUGIN_ROOT is set correctly
Secret retrieval emptySecret name typoList secrets: 
doppler secrets ls --project X
mise cache staleDuration expiredClear cache or reduce duration setting
Multiple configs confusionSecrets differ across envsUse explicit --config flag for each command
问题原因解决方案
密钥未找到指定的项目/配置错误使用
doppler secrets ls --project X --config
验证
认证测试返回401错误令牌过期或无效重新生成令牌，重新添加至Doppler
doppler run 命令挂起CLI等待输入添加
--no-interactive
参数
令牌前缀不匹配使用了错误的令牌类型检查预期格式（pypi-、ghp-、AKIA等）
验证脚本未找到目录上下文错误确保CLAUDE_PLUGIN_ROOT已正确设置
密钥检索结果为空密钥名称拼写错误列出密钥：
doppler secrets ls --project X
mise缓存过期缓存时长已到清除缓存或缩短时长设置
多配置环境混淆不同环境的密钥不同为每个命令使用明确的--config参数