Secrets Management (Don't Commit Your Keys)
There's a moment that happens to almost every developer once. You wire up a third-party service, paste the API key right into the code to "get it working," push the branch - and three days later get an email from your cloud provider about a $4,000 bill, or a note from a security bot that found your key in a public repo. Your stomach drops. You weren't careless, exactly. Nobody ever showed you where keys are supposed to live, so you put it where the code could see it.
This guide fixes that gap. By the end you'll know exactly what counts as a secret, why secrets leak (it's almost always the same way), how to keep them out of your code and out of Git, and how real teams store and rotate them so a leak is a shrug instead of a disaster. The core idea is calm and simple: a secret is a key to something that costs money or data, so you treat it like a key - you don't tape it to the front door.
How to read this
- You leaked a secret right now and need to act? Jump to the leaked-secret cheat-card in Phase 3 and follow it top to bottom. Then come back and read the rest when your heart rate is normal.
- Want it to finally make sense? Read in order. Each phase builds on the one before, starting with the mental model that makes every rule afterward obvious.
The phases
- What Counts as a Secret & Why It Leaks - the mental model (a secret is a key to something that costs money or data), the four kinds you'll meet, and the number-one way they escape: hardcoded into source and committed.
- Keep Them Out of Code - config via environment variables and
.env,.gitignoreand.env.example, pre-commit secret scanners, and the hard truth that a committed secret lives in Git history forever - so you rotate it. - Real Secrets Management - how teams do it for production: a secrets manager that stores keys centrally, encrypted and access-controlled; injecting them at runtime instead of baking them into images; least privilege; and making rotation routine. Includes the leaked-secret cheat-card.
This guide is about keeping secrets safe. Where config values come from in the first place - environment variables,
.env, YAML, precedence - is its own guide: Environment Variables & Config. And if a secret has already reached a remote and you're wondering whethergit reverthides it (it doesn't), see Git Disaster Recovery.