doppler-secret-validation

Doppler シークレットの検証

自己進化型スキル：このスキルは使用を重ねることで改善されます。手順に誤りがある、パラメーターが変わった、または回避策が必要だった場合は、先延ばしにせず、このファイルをすぐに修正してください。実際に再現できる問題がある場合にのみ更新してください。

概要

Doppler のシークレット管理で、API トークンや認証情報を安全に追加、検証、テストするワークフローです。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください。

• ユーザーが API トークンや認証情報（PyPI、GitHub、AWS など）を提供した場合
• ユーザーが「Doppler に追加」「シークレットを保存」「トークンを検証」と言及した場合
• ユーザーが本番環境で使用する前に認証をテストしたい場合
• ユーザーがシークレットの保存と取得を確認する必要がある場合

ワークフロー

ステップ 1：トークンの形式をテストする（Doppler に追加する前）

Doppler に保存する前に、トークンの形式を検証します。

# Check token format, length, prefix
python3 -c "token = 'TOKEN_VALUE'; print(f'Prefix: {token[:20]}...'); print(f'Length: {len(token)}')"

一般的なトークン形式：

• PyPI：pypi-...（179 文字）
• GitHub：ghp_...（40 文字以上）
• AWS：20 文字のアクセスキー＋40 文字のシークレット

ステップ 2：シークレットを Doppler に追加する

doppler secrets set SECRET_NAME="value" --project PROJECT --config CONFIG

例：

doppler secrets set PYPI_TOKEN="pypi-AgEI..." \
  --project private-config --config prd

重要：CLI は --note をサポートしていません。メモはダッシュボードから追加してください。

1. https://dashboard.doppler.com
2. 移動先：PROJECT → CONFIG → SECRET_NAME
3. 編集 → 説明的なメモを追加

ステップ 3：保存を検証する

同梱の検証スクリプトを使用します。

/usr/bin/env bash << 'VALIDATE_EOF'
ROOT="$(cc-plugin-root devops-tools)"
cd "$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 による環境変数の注入が機能する

例：

uv run scripts/validate_secret.py \
  --project private-config \
  --config prd \
  --secret PYPI_TOKEN

ステップ 4：API 認証をテストする

同梱の認証テストスクリプトを使用します（特定の API に合わせて test_api_authentication() を調整してください）。

/usr/bin/env bash << 'CONFIG_EOF'
ROOT="$(cc-plugin-root devops-tools)"
doppler run --project PROJECT --config CONFIG -- \
  "$ROOT/skills/doppler-secret-validation/scripts/test_api_auth.py" \
    --secret SECRET_NAME \
    --api-url API_ENDPOINT
CONFIG_EOF

例（PyPI）：

doppler run --project private-config --config prd -- \
  uv run scripts/test_api_auth.py \
    --secret PYPI_TOKEN \
    --api-url https://upload.pypi.org/legacy/

ステップ 5：使用方法を記録する

検証後、ユーザー向けに使用方法を記録します。

/usr/bin/env bash << 'CONFIG_EOF_2'
# Pattern 1: Doppler run (recommended for CI/scripts)
doppler run --project PROJECT --config CONFIG -- COMMAND

# Pattern 2: Manual export (for troubleshooting)
export SECRET_NAME=$(doppler secrets get SECRET_NAME \
  --project PROJECT --config CONFIG --plain)
CONFIG_EOF_2

ステップ 5b：ディレクトリ単位の Doppler 設定（ローカル開発）

ディレクトリごとに認証情報を設定するには、一度 doppler setup でディレクトリを Doppler のプロジェクト／設定に紐付けます。その後、そのディレクトリで実行する doppler run では、--project／--config を指定しなくても設定が適用されます。

cd ~/project && doppler setup --project myproject --config prd --no-interactive
doppler run -- COMMAND

GitHub トークンは例外です：Doppler から GH_TOKEN／GITHUB_TOKEN をディレクトリに注入しないでください（ADR 2026-06-21）。GitHub の複数アカウント認証は、リポジトリの origin ホストエイリアスに基づいて行われ、トークンは ~/.claude/tools/bin/gh-token-for-repo によってリポジトリごとに新たに解決されます。

一般的なパターン

複数の設定（dev、stg、prd）

複数の環境にシークレットを追加します。

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

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

複数の設定にまたがるシークレットの確認

/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

セキュリティガイドライン

1. シークレット全体をログに記録しない：${SECRET:0:20}... を使用してマスキングします
2. doppler run を優先する：シークレットのスコープを単一のコマンドに限定します
3. パイプへの出力にのみ --plain を使用する：人が読み取る形式ではシークレットがマスキングされます
4. 環境ごとに設定を分ける：dev/stg/prd を分離します

同梱リソース

• scripts/validate_secret.py - 検証一式（存在確認、取得、注入）
• scripts/test_api_auth.py - API 認証テスト用テンプレート
• references/doppler-patterns.md - 一般的な CLI パターンと例

参考資料

• Doppler のドキュメント：https://docs.doppler.com/docs
• CLI のインストール：brew install dopplerhq/cli/doppler
• 包括的なパターンについては、doppler-patterns.md を参照してください

---

トラブルシューティング

問題	原因	解決策
シークレットが見つからない	プロジェクト／設定の指定が誤っている	doppler secrets ls --project X --config で確認します
認証テストが 401 で失敗する	トークンの期限切れまたは無効	トークンを再生成し、Doppler に再追加します
doppler run が停止する	CLI が入力待ちになっている	--no-interactive フラグを追加します
トークンのプレフィックスが一致しない	誤った種類のトークンを使用している	期待される形式（pypi-、ghp-、AKIA など）を確認します
検証スクリプトが見つからない	ディレクトリのコンテキストが誤っている	cc-plugin-root devops-tools を使ってプラグインのルートを確認し、その後 cd でスキルのディレクトリに移動します
シークレットの取得結果が空	シークレット名の入力ミス	シークレットを一覧表示します：doppler secrets ls --project X
複数の設定が混乱を招いている	環境ごとにシークレットが異なる	各コマンドで明示的に --config フラグを使います

実行後の振り返り

このスキルの完了後、タスクを終了する前に振り返ってください：

0. 現在の場所を確認します。 — 編集する前に、この SKILL.md の正式なパスを見つけます。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは何ですか？ — 推奨されるプラクティスとして取り入れます。
3. 現状とずれている点は何ですか？ — 現実と一致しなくなったスクリプト、参照資料、依存関係を修正します。
4. 記録します。 — きっかけ、修正内容、根拠を記載した進化ログのエントリーを残します。

先送りしないでください。次回の実行は、あなたが残した状態を引き継ぎます。