Your app needs passwords and keys to reach its database, its payment provider, its AI services. Put even one of those in your code, and the day you share that code, push it, or paste it to your agent, you hand strangers the keys. This chapter keeps every secret out of your codebase from the start.
2.6.1What counts as a secret
A secret is any value that lets someone act as you or your app: a database password, an API key, a payment token, an auth signing key. The test is simple: if leaking it costs you money or access, it is a secret.
Everything else is just config, plain settings like a page title or a feature switch. Config is safe to share; secrets never are. This chapter is about the secrets.
2.6.2Keys never touch the code
The rule a professional never breaks: a secret is never written in the code itself. Code gets shared, pushed to your repo, copied between machines, pasted to your agent, and a key sitting inside it travels to every one of those places.
Instead, secrets live outside the code, in environment variables: values the app reads from its surroundings at startup, by name. The code says "give me the database password," never the password itself.
2.6.3One .env file, never committed
The standard home for those values is a file named .env in your project, one KEY=value per line, that your code reads when it starts. This file never leaves your machine: you add it to your .gitignore so version control skips it and it is never committed.
So anyone else, including your future self, knows which keys exist without seeing their values, you commit a .env.example beside it: the same key names with blank or fake values. The real secrets stay local, the list of what is needed is shared.
2.6.4Rotate anything that leaks
If a secret ever slips out, in a screenshot, a commit, a pasted log, treat it as burned. Rotate it: generate a fresh key at the provider and replace the old one, which instantly makes the leaked copy useless. Do it the moment you notice, not later.
Watch out: a secret pushed to your repo does not disappear when you delete the line, it stays in the history. Rotating the key is the only real fix.
2.6.5Wire it up for your stack
This prompt has your agent set secret handling up correctly for whatever stack you chose:
Act as a senior engineer setting up secret handling for
my project. Create a .env file for my stack and add it to
.gitignore so it is never committed. Create a .env.example
with the same keys but empty values. Move any keys already
sitting in my code into .env and read them from there.
Tell me what each key is for.
My stack:
Do this now: move every key out of your code into a git-ignored .env, and commit a .env.example beside it so the list of needed keys is shared but the values are not.
