Doppler Management Skill

Purpose: Complete Doppler secret management setup with scripts, templates, and GitHub integration

Category: Secret Management / DevOps

Capabilities

This skill provides comprehensive Doppler setup for centralized secret management:

Project Setup - Create Doppler project and environments
Script Generation - Generate migration, run-wrapper, and GitHub setup scripts
Documentation - Generate complete integration guides
GitHub Integration - Setup automatic secret sync to GitHub Actions
Multi-Environment - Support for dev, staging, production configs

Resources Available

Scripts (`skills/doppler-management/scripts/`)

migrate-to-doppler.sh - Migration script template

Detects environment variables from project
Generates Doppler upload commands
Uses placeholders (security compliant)
Supports multi-environment (dev, stg, prd)

run-with-doppler.sh - Command wrapper template

Injects Doppler secrets at runtime
Supports environment switching
Works with any command

setup-doppler-github.sh - Interactive GitHub integration wizard

Guides through GitHub App installation
Configures sync mappings
Creates GitHub Environments
Verifies secret sync

Documentation Templates (`skills/doppler-management/templates/docs/`)

README.md - Main documentation index

Quick start guide
Command reference
Troubleshooting

integration-guide.md - Complete integration guide

Local development setup
Framework integration (FastAPI, Next.js, etc.)
CI/CD configuration
Team workflows

github-integration.md - GitHub App setup guide

Step-by-step installation
Sync configuration
Workflow examples
Security best practices

environment-setup.md - Multi-environment configuration

.env file management
Environment-specific configs
Service configuration guides
Migration instructions

PLUGIN-DESIGN.md - Plugin architecture documentation

Design decisions
Template system
Reusability patterns

Workflow Templates (`skills/doppler-management/templates/workflows/`)

test-doppler-secrets.yml - GitHub Actions test workflow

Verifies secret sync
Tests all environments
Validates configuration

Usage Patterns

Pattern 1: Complete Setup (Recommended)

Use when setting up Doppler for the first time:

# Command: /foundation:doppler-setup [project-name]

Steps executed:
1. Check Doppler CLI installation
2. Detect project name and GitHub repo
3. Create Doppler project and environments
4. Generate scripts in scripts/doppler/
5. Generate documentation in docs/doppler/
6. Create GitHub Actions workflow
7. Update .gitignore
8. Display setup summary

Pattern 2: Script Generation Only

Use when you need to regenerate scripts:

Invoke skill: doppler-management

Context: "Generate Doppler scripts for [project-name]"

Output:
- scripts/doppler/migrate-to-doppler.sh
- scripts/doppler/run-with-doppler.sh
- scripts/doppler/setup-doppler-github.sh

Pattern 3: Documentation Generation

Use when you need fresh documentation:

Invoke skill: doppler-management

Context: "Generate Doppler documentation for [project-name]"

Output:
- docs/doppler/README.md
- docs/doppler/integration-guide.md
- docs/doppler/github-integration.md
- docs/doppler/environment-setup.md

Template Variables

Automatic Detection

When invoked, this skill automatically detects:

From .claude/project.json:

{{PROJECT_NAME}} - Project name
{{TECH_STACK}} - Framework information
{{ENVIRONMENT_VARS}} - List of environment variables

From git remote:

{{GITHUB_REPO}} - Repository owner/name

From environment:

{{GENERATION_DATE}} - Current date

Environment Variable Detection

Scans these sources in order:

Existing .env* files
specs/ directory (service requirements)
.claude/project.json (declared variables)
Code analysis (os.getenv, process.env patterns)

Variable Categories

Automatically categorizes detected variables:

Google APIs - GOOGLE_API_KEY, GOOGLE_FILE_SEARCH_STORE_ID
Supabase - SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY
Application - ENVIRONMENT, PORT, DEBUG
AI Services - OPENAI_API_KEY, ANTHROPIC_API_KEY
Payments - STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY
Custom - Any other detected variables

Security Compliance

CRITICAL: All generated files follow security rules:

@~/.claude/plugins/marketplaces/dev-lifecycle-marketplace/docs/security/SECURITY-RULES.md

Guaranteed Practices

✅ All scripts use placeholders:

# CORRECT - Always generated this way
GOOGLE_API_KEY=your_google_api_key_here
SUPABASE_URL=https://your-project.supabase.co

✅ Never hardcodes secrets:

All values are placeholders
User must manually add real credentials
Scripts check for placeholder values before execution

✅ Documentation includes acquisition guides:

Where to get each API key
Step-by-step setup for each service
Links to service dashboards

✅ Protects sensitive files:

Auto-updates .gitignore
Adds .doppler.env, doppler.yaml, .doppler/
Protects all .env.* except .env.example

Framework-Specific Customization

FastAPI (Python)

Detected patterns:

os.getenv(), os.environ.get(), os.environ[]
pydantic.BaseSettings

Generated code:

import os
api_key = os.getenv("GOOGLE_API_KEY")

Run command:

./run-with-doppler.sh uvicorn api.main:app --reload

Next.js (TypeScript)

Detected patterns:

process.env.NEXT_PUBLIC_*
process.env.* in API routes

Generated code:

// Client-side
const url = process.env.NEXT_PUBLIC_SUPABASE_URL

// Server-side
const key = process.env.SUPABASE_SERVICE_KEY

Run command:

./run-with-doppler.sh npm run dev

Generic Projects

Works with any tech stack that uses environment variables.

Integration with Foundation Commands

`/foundation:doppler-setup`

Primary command that orchestrates complete Doppler setup:

**Arguments**: [project-name]

Process:
1. Invoke doppler-management skill for detection
2. Create Doppler project via CLI
3. Generate all scripts from templates
4. Generate all documentation from templates
5. Create GitHub Actions workflow
6. Update .gitignore
7. Display summary and next steps

`/foundation:env-vars`

Complementary command for environment variable management:

Integration:
- Detects vars → Provides to doppler-management skill
- Generates .env files → Used by migration script
- Multi-environment support → Matches Doppler configs

File Organization

Generated Structure

project/
├── scripts/
│   └── doppler/
│       ├── migrate-to-doppler.sh       # Migration script
│       ├── run-with-doppler.sh         # Run wrapper
│       └── setup-doppler-github.sh     # GitHub setup wizard
├── docs/
│   └── doppler/
│       ├── README.md                    # Documentation index
│       ├── integration-guide.md         # Integration guide
│       ├── github-integration.md        # GitHub setup
│       ├── environment-setup.md         # Environment guide
│       └── PLUGIN-DESIGN.md            # Architecture docs
├── .github/
│   └── workflows/
│       └── test-doppler-secrets.yml    # Test workflow
└── DOPPLER-SETUP-SUMMARY.md           # Quick reference

Benefits of Organization

✅ Scripts in scripts/doppler/

Not cluttering project root
Easy to find and maintain
Grouped by purpose

✅ Docs in docs/doppler/

Organized documentation
Easy navigation
Searchable

✅ Workflows in .github/workflows/

Standard GitHub location
Auto-discovered by Actions
Version controlled

Examples

Example 1: New Project Setup

Scenario: Fresh project, never used Doppler

# User runs:
/foundation:doppler-setup my-saas-app

# Skill detects:
- Project name: my-saas-app
- GitHub repo: username/my-saas-app (from git remote)
- Tech stack: FastAPI + Next.js (from project.json)
- Environment vars: 12 detected

# Skill generates:
✓ scripts/doppler/migrate-to-doppler.sh (with 12 vars)
✓ scripts/doppler/run-with-doppler.sh
✓ scripts/doppler/setup-doppler-github.sh
✓ docs/doppler/ (all 4 guides)
✓ .github/workflows/test-doppler-secrets.yml
✓ DOPPLER-SETUP-SUMMARY.md

# User next steps:
1. Edit scripts/doppler/migrate-to-doppler.sh (add real secrets)
2. Run: scripts/doppler/migrate-to-doppler.sh
3. Run: scripts/doppler/setup-doppler-github.sh
4. Test: scripts/doppler/run-with-doppler.sh uvicorn api.main:app

Example 2: Regenerate After Adding Services

Scenario: Added Stripe, need updated scripts

# User adds to project.json:
"environment_variables": {
  "stripe": ["STRIPE_SECRET_KEY", "STRIPE_PUBLISHABLE_KEY"]
}

# User runs:
/foundation:doppler-setup  # Detects existing setup

# Skill detects:
- Existing Doppler project
- New variables: STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY
- Existing migration script

# Skill offers:
"Detected existing Doppler setup. Options:"
1. Regenerate migration script (includes new Stripe vars)
2. Update documentation
3. Both

# User selects: Both

# Skill updates:
✓ scripts/doppler/migrate-to-doppler.sh (now includes Stripe)
✓ docs/doppler/environment-setup.md (Stripe section added)

Troubleshooting Guide

Issue: Scripts not executable

Fix:

chmod +x scripts/doppler/*.sh

Issue: Variables not detected

Causes:

Not in standard .env location
Not declared in project.json
Using non-standard naming

Fix: Manually add to migration script or declare in project.json:

"environment_variables": {
  "custom": ["MY_CUSTOM_VAR"]
}

Issue: GitHub integration fails

Fix: See docs/doppler/github-integration.md troubleshooting section

Skill Invocation

Direct Invocation

Skill: doppler-management

Context: "Setup Doppler for [project-name]"

The skill will:
1. Detect project context
2. Generate all scripts and docs
3. Provide next steps

Via Command

/foundation:doppler-setup [project-name]

The command internally invokes this skill.

Maintenance

Updating Templates

Templates are in skills/doppler-management/templates/

To update:

Edit template files
Test with sample project
Commit changes
Regenerate documentation if needed

Adding New Services

To add support for a new service:

Add to variable categories (in detection logic)
Update migration script template
Add service section to environment-setup.md
Test detection and generation

Related Skills

environment-setup - General environment configuration
mcp-configuration - MCP server setup
project-detection - Tech stack detection

Version History

v1.0.0 (2025-11-12)

Initial release
Complete script generation
Multi-environment support
GitHub integration
Comprehensive documentation

Maintained by: Foundation Plugin Team Category: Secret Management Tags: doppler, secrets, environment, github, ci-cd, deployment

Doppler Management Skill

Doppler Management Skill

Capabilities

Resources Available

Scripts (skills/doppler-management/scripts/)

Documentation Templates (skills/doppler-management/templates/docs/)

Workflow Templates (skills/doppler-management/templates/workflows/)

Usage Patterns

Pattern 1: Complete Setup (Recommended)

Pattern 2: Script Generation Only

Pattern 3: Documentation Generation

Template Variables

Automatic Detection

Environment Variable Detection

Variable Categories

Security Compliance

Guaranteed Practices

Framework-Specific Customization

FastAPI (Python)

Next.js (TypeScript)

Generic Projects

Integration with Foundation Commands

/foundation:doppler-setup

/foundation:env-vars

File Organization

Generated Structure

Benefits of Organization

Examples

Example 1: New Project Setup

Example 2: Regenerate After Adding Services

Troubleshooting Guide

Issue: Scripts not executable

Issue: Variables not detected

Issue: GitHub integration fails

Skill Invocation

Direct Invocation

Via Command

Maintenance

Updating Templates

Adding New Services

Related Skills

Version History

Related Skills

Scripts (`skills/doppler-management/scripts/`)

Documentation Templates (`skills/doppler-management/templates/docs/`)

Workflow Templates (`skills/doppler-management/templates/workflows/`)

`/foundation:doppler-setup`

`/foundation:env-vars`