Environment Configuration Safety

Foundation · ENV-01, ENV-02 · Priority: P1

Why It Matters

AI tools generate .env files with placeholder values during development. Without .env.example, new team members don't know what variables are needed — they skip critical ones or ask for real secrets over insecure channels. And if .env with real credentials gets committed to git, the secrets are permanently in history.

Affected Stack: Any framework using environment variables

ENV-01 — .env.example exists

The Problem

Without .env.example, there's no documentation of required environment variables. A new developer (or a deployment script) has no way to know what's needed:

# ❌ No .env.example — developer guesses
# Which variables does this app need?
# What's the format? What's required vs optional?

The Fix

Create .env.example listing every required variable with placeholder values:

# ✅ .env.example — documents all required variables
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
STRIPE_SECRET_KEY=sk_test_your-key
STRIPE_WEBHOOK_SECRET=whsec_your-secret
NEXT_PUBLIC_APP_URL=http://localhost:3000

Important: Never put real values in .env.example. Only placeholder formats.

ENV-02 — .env not committed to git

Priority: P0 — Committed secrets are permanently in git history.

The Problem

AI tools sometimes create .env files and commit them before .gitignore is properly configured. Even after deletion, the secrets remain in git history:

# ❌ Real secrets in git history
git log --all --full-history -- .env
# commit abc123 — "initial setup" ← secrets are HERE forever

The Fix

Add .env* to .gitignore (except .env.example)
If .env was ever committed, rotate ALL secrets immediately
Consider using git filter-branch or BFG to purge history

# ✅ .gitignore
.env
.env.local
.env.production
!.env.example

References

Related Checks

Is your app safe? Run Free Scan →