Environment Manager

Overview

This skill helps manage environment variables and secrets across multiple environments (development, staging, production). It detects missing variables, identifies mismatches, audits for exposed secrets, and helps safely rotate credentials without downtime.

Instructions

Auditing Environment Variables

1. Find all env var references in code. Match both dot access and bracket access, and both process.env and process.env["NAME"]:

   grep -rhoE "process\.env(\.[A-Za-z_][A-Za-z0-9_]*|\[[\"'][A-Za-z_][A-Za-z0-9_]*[\"']\])" src/ \
     --include="*.ts" --include="*.js" | grep -oE "[A-Za-z_][A-Za-z0-9_]*" | grep -vE "^(process|env)$" | sort -u
   

   For Python, which covers os.environ["X"], os.environ.get("X") and os.getenv("X"):

   grep -rhoE "os\.(environ(\.get)?|getenv)[\[(][\"'][A-Z_][A-Z0-9_]*[\"']" src/ --include="*.py" | \
     grep -oE "[A-Z][A-Z0-9_]*" | sort -u
   

   Both commands miss names built at runtime (process.env[key]); check those by reading the code.

2. Compare against what's defined:

   # From .env.example or .env
   grep -v '^#' .env.example | grep '=' | cut -d'=' -f1 | sort -u
   

3. Report:

   • Variables referenced in code but missing from .env.example → ⚠️ undocumented
   • Variables in .env.example but never referenced in code → ℹ️ possibly stale
   • Variables with no default and no validation → 🔴 app will crash if missing

Comparing Environments

1. Get variable lists from each environment:

   • Local: Parse .env or .env.local
   • CI/CD: Check platform config (GitHub Actions secrets, GitLab CI variables)
   • Hosting: Check platform env vars (Vercel, Railway, Heroku config)
   • Secrets manager: Query Doppler, AWS SSM, or Vault

2. Build a comparison matrix:

   Variable              | dev | staging | prod | Notes
   DATABASE_URL          | ✓   | ✓       | ✓    | Different per env ✓
   STRIPE_SECRET_KEY     | ✓   | ✓       | ✗    | ⚠️ Missing in prod!
   REDIS_URL             | ✗   | ✓       | ✓    | ℹ️ Not needed locally
   NEXT_PUBLIC_API_URL   | ✓   | ✓       | ✓    | Verify values differ
   

3. Flag issues:

   • Variable present in staging but missing in production → likely deployment bug
   • Same secret value across dev and prod → security risk
   • Public-prefixed variables with secret values → will be exposed to client

Secret Rotation

1. Identify the secret to rotate (API key, database password, JWT secret)
2. Check where it's used:

   grep -rn "THE_VAR_NAME" . --include="*.ts" --include="*.js" --include="*.yml" --include="*.yaml" --include="Dockerfile"
   

3. Generate rotation plan:
   • For API keys: Create new key → update all environments → verify → revoke old key
   • For database passwords: Update password → update connection strings → restart services
   • For JWT secrets: Implement dual-key validation → deploy → set new primary → remove old
4. Verify no hardcoded values exist (should all reference env vars)

Setting Up a New Environment

1. Start from .env.example as the template
2. Categorize each variable:
   • Shared config (feature flags, API URLs) → copy and adjust for the new env
   • Secrets (API keys, passwords) → generate new ones, never copy from another env
   • Infrastructure (database URLs, Redis URLs) → get from the new env's infra
3. Validate the new environment against the list of required variables. Node 20.6+ loads a file with --env-file and needs no dependency:

   node --env-file=.env -e "
     const required = ['DATABASE_URL', 'STRIPE_SECRET_KEY', 'APP_BASE_URL'];
     const missing = required.filter(k => !process.env[k]);
     if (missing.length) { console.error('missing: ' + missing.join(', ')); process.exit(1); }
     console.log('all ' + required.length + ' required variables are set');
   "
   

   Run this in CI before the deploy step. A schema validator such as envalid or zod gives the same check inside the app at startup.

Examples

Example 1: Audit for Missing Variables

User prompt:

We keep getting "undefined" errors in staging. Can you audit our env vars?

Agent output:

Scanned src/ for environment variable references. Found 34 unique variables.

🔴 Missing from .env.example (undocumented):
  OPENAI_API_KEY        — referenced in src/lib/ai.ts:12
  WEBHOOK_SECRET        — referenced in src/api/webhooks.ts:8
  RATE_LIMIT_MAX        — referenced in src/middleware/rateLimit.ts:3

⚠️ Referenced but no validation/default:
  SMTP_HOST             — used in src/lib/email.ts:5, crashes if undefined
  CACHE_TTL             — used in src/lib/cache.ts:2, parseInt(undefined) = NaN

ℹ️ In .env.example but never referenced in code:
  LEGACY_API_URL        — possibly from a removed feature
  DEBUG_MODE            — no references found

Recommendation: Add the 3 undocumented vars to .env.example, add default
values for SMTP_HOST and CACHE_TTL, and remove the 2 stale entries.

Example 2: Sync Staging with Production

User prompt:

We're about to launch. Compare staging and production env vars to make sure nothing is missing.

Agent output:

Compared 41 variables across staging and production:

🔴 Missing in production (3):
  STRIPE_WEBHOOK_SECRET  — payments will fail without this
  SENTRY_DSN             — no error tracking in prod
  FEATURE_FLAG_API_KEY   — feature flags will default to off

⚠️ Same value in both environments (2):
  JWT_SECRET             — using identical secret is a security risk
  DATABASE_URL           — pointing to same DB! This should differ.

✓ Correctly different (28 vars)
ℹ️ Staging-only (8 vars) — debug/test vars, expected

Action items:
1. Set STRIPE_WEBHOOK_SECRET in prod (get from Stripe Dashboard → Webhooks)
2. Set SENTRY_DSN in prod (get from Sentry → Project Settings → Client Keys)
3. Generate a new JWT_SECRET for prod: openssl rand -base64 32
4. Verify DATABASE_URL points to the production database, not staging

Guidelines

• Never print or log actual secret values — show only variable names and metadata
• When comparing environments, flag identical secrets as a security concern
• Always check for NEXT_PUBLIC_ or VITE_ prefixed vars that contain actual secrets
• Recommend .env.example as the source of truth, committed to git (without values)
• For rotation, always plan for zero-downtime: new key → deploy → verify → revoke old
• Check CI/CD pipeline configs too — secrets there often go stale after renames
• Suggest validation libraries (envalid, zod) to catch missing vars at startup, not runtime