doppler-workflows

Doppler Credential Workflows

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Publishing Python packages to PyPI
• Rotating AWS access keys
• Managing credentials across multiple services
• Troubleshooting authentication failures (403, InvalidClientTokenId)
• Setting up Doppler credential injection patterns
• Multi-token/multi-account strategies

Quick Reference

Core Pattern: Doppler CLI

Standard Usage:

doppler run --project <project> --config <config> --command='<command>'

Why --command flag:

• Official Doppler pattern (auto-detects shell)
• Ensures variables expand AFTER Doppler injects them
• Without it: shell expands $VAR before Doppler runs → empty string

---

Quick Start Examples

PyPI Publishing

doppler run --project private-config --config dev \
  --command='uv publish --token "$PYPI_TOKEN"'

AWS Operations

doppler run --project aws-credentials --config dev \
  --command='aws s3 ls --region $AWS_DEFAULT_REGION'

---

Best Practices

1. Always use --command flag for credential injection
2. Use project-scoped tokens (PyPI) for better security
3. Rotate credentials regularly (90 days recommended)
4. Document with Doppler notes: doppler secrets notes set <SECRET> "<note>"
5. Use stdin for storing secrets: echo -n 'secret' | doppler secrets set
6. Test injection before using: echo ${#VAR} to verify length
7. Multi-token naming: SERVICE_TOKEN_{ABBREV} for clarity

---

Reference Documentation

For detailed information, see:

• PyPI Publishing - Token setup, publishing, troubleshooting
• AWS Credentials - Rotation workflow, setup, troubleshooting
• Multi-Service Patterns - Multiple PyPI packages, multiple AWS accounts
• AWS Workflow - Complete AWS credential management guide

Bundled Specifications:

• PYPI_REFERENCE.yaml - Complete PyPI spec
• AWS_SPECIFICATION.yaml - AWS credential architecture

---

Local Development: Directory-Scoped Doppler Config

For local development, bind the project directory to its Doppler project/config once, then scope each command with doppler run:

cd ~/project && doppler setup --project private-config --config prd --no-interactive
doppler run -- COMMAND   # secrets such as PYPI_TOKEN exist for this command only

For a value needed across several commands in one shell, export it explicitly: export PYPI_TOKEN="$(doppler secrets get PYPI_TOKEN --plain)".

Do NOT inject GitHub tokens this way (ADR 2026-06-21). GitHub multi-account auth is driven by the repo's origin host-alias ([email protected]<account>:…). A token resolves fresh per-repo via ~/.claude/tools/bin/gh-token-for-repo; an ambient GH_TOKEN outranks the isolated gh profile and 401s after a rotation. The .secrets/gh-token-* files are deleted.

---

PyPI Publishing Policy

For PyPI publishing, see pypi-doppler skill for LOCAL-ONLY workspace policy.

Do NOT configure PyPI publishing in GitHub Actions or CI/CD pipelines.

---

Troubleshooting

Issue	Cause	Solution
403 on PyPI publish	Token expired or wrong scope	Regenerate project-scoped token, update in Doppler
InvalidClientTokenId (AWS)	Access key rotated or deleted	Run AWS key rotation workflow, update Doppler
Variable expands empty	Using $VAR without --command	Always use --command='...$VAR...' pattern
Doppler CLI not found	Not installed	brew install dopplerhq/cli/doppler
Wrong config selected	Ambiguous project/config	Specify both --project and --config explicitly
Wrong project picked up	Directory not bound or bound wrongly	doppler configure to inspect; re-run doppler setup
Secret retrieval slow	One doppler secrets get per call	Fetch once per shell with export VAR="$(doppler secrets get VAR --plain)"
Token length mismatch	Copied with extra whitespace	Trim token: echo -n 'secret' | doppler secrets set

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.