Rules 1–3: keep secrets out of git
1. Ignore every .env file except the template
.env* !.env.example
One pattern covers .env, .env.local, .env.production and whatever comes next. Check with git check-ignore -v .env.local. Details and recovery steps: how to hide .env from git.
2. Make .env.example the source of truth
Every key the app reads is in .env.example, with a comment on where the value comes from. New developers run cp .env.example .env and fill in the blanks. Generate it from a working file with the .env.example generator, and update it in the same PR that adds a variable.
3. Scan before you push or share
AWS keys, Stripe live keys, GitHub tokens and private keys have recognisable formats. Run the ENV leak checker on a file before it goes into a ticket or chat, and add gitleaks as a pre-commit hook or CI step for the repository.
Rules 4–6: secrets that are hard to guess and easy to replace
4. Generate secrets, never invent them
A human-typed secret like my-super-secret-key is short and guessable. A generated one has 256 random bits: openssl rand -base64 32, or the secret generator with presets for JWT, sessions and API keys.
5. One secret per purpose, per environment
Don't reuse JWT_SECRET as the session secret, and never share a value between staging and production. A leak then affects one feature in one environment, and rotating it breaks nothing else.
6. Rotate on suspicion and on offboarding
Rotate whenever a secret appeared in a log, a screenshot, a ticket or chat, and when someone with access leaves. A scheduled rotation (e.g. every 90 days) is a sensible baseline for database, payment and admin credentials; with a secrets manager it can be automated.
Rules 7–8: validate and separate environments
7. Validate at startup and fail fast
import { z } from "zod";
export const env = z
.object({
NODE_ENV: z.enum(["development", "test", "production"]),
DATABASE_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
})
.parse(process.env);Alternatives: envalid or convict for Node.js, @t3-oss/env-nextjs for Next.js, pydantic-settings for Python, envconfig for Go. The .env validator checks the file's syntax; a schema checks what the app needs.
8. Keep production values off developer machines
Local DATABASE_URL points to a local database, not staging. Use separate accounts or projects (Stripe test mode, a dev Supabase project, a dev AWS account) so a laptop leak can't touch production.
Rules 9–10: public variables and drift
9. Know which variables are public
| Framework | Public prefix | Everything else |
|---|---|---|
| Next.js | NEXT_PUBLIC_ | server only |
| Vite | VITE_ | not exposed to import.meta.env in the client |
| Create React App (deprecated) | REACT_APP_ | not available |
| Nuxt | NUXT_PUBLIC_ | server only (runtimeConfig) |
| SvelteKit | PUBLIC_ | $env/static/private |
Public variables are inlined into JavaScript at build time and readable by anyone. A Stripe secret key or a Supabase service-role key must never get one of these prefixes. More in NEXT_PUBLIC_ variables explained.
10. Check for drift before every release
Staging and production diverge quietly. Compare them with the ENV diff checker as part of the release checklist; a key that exists only in staging is a crash waiting for its first request in production.
What goes where
| Value | Where it lives | In git? |
|---|---|---|
| Key names + safe defaults | .env.example | yes |
| Your local secrets | .env / .env.local | no |
| CI secrets | GitHub Actions / GitLab CI secrets | no |
| Production secrets | host settings or a secrets manager | no |
| Non-secret per-mode config | .env.development, .env.production (Next.js, Vite) | yes, if truly non-secret |
When a team outgrows passing .env files around, a secrets manager adds access control, audit logs and rotation. The comparison dotenv vs secrets manager covers when that point is reached.
If a secret leaks
- Revoke or rotate at the provider (AWS IAM, Stripe, GitHub, your database). This is the step that stops misuse.
- Check usage logs for activity you don't recognise.
- Remove it from git history with
git filter-repo, force-push, and have collaborators re-clone. - Notify affected users if customer data could have been exposed.
Frequently asked questions
Is .gitignore enough to keep .env safe?
It only stops future commits. A secret that is already in git history stays there; rotate every value that was committed, then rewrite history with git filter-repo.
How often should secrets be rotated if nothing leaked?
There's no universal rule. A common baseline is every 90 days for high-value credentials (database, payment provider, admin keys) and always when someone with access leaves. Public IDs need no rotation.
Do these rules apply to a solo project?
Mostly yes: generated secrets, .gitignore, startup validation and leak scanning cost nothing. What you can skip alone is team process like access reviews and audit logs.
Should .env files be encrypted?
For sharing, yes: encrypt before sending (e.g. with the ENV encrypt tool). For storage in git, use a tool built for it such as SOPS or dotenvx, or keep secrets in a secrets manager instead.
What's the fastest way to check if I already leaked a secret?
Paste the file into the ENV leak checker for a quick pattern scan, and run gitleaks or trufflehog over the whole git history, which also covers deleted files.