Secrets Management Basics

What is a secret

A secret is any value that grants access or must stay confidential: API keys, client secrets, tokens, signing keys, database passwords. If knowing it lets someone act as you or read protected data, treat it as a secret.

The defining risk is that secrets are credentials, not just configuration. A leaked endpoint URL is awkward; a leaked client secret is a breach. Because of that asymmetry, secrets deserve stricter handling than ordinary settings — tighter storage, no casual logging, and a plan for rotation. The first discipline is simply to recognise which of your values are secrets so you can treat them accordingly.

Keep them out of the repo

The most common leak is a secret committed to source control. Once it is in history it is effectively public to anyone with repository access, and removing it from history is painful and unreliable.

• Never commit secrets — not in code, config files, or fixtures.
• Use ignore rules so local secret files cannot be added by accident.
• Scan for leaks in your pipeline to catch mistakes early.

Provide a committed template — an example file with the names of required secrets but no values — so contributors know what to supply without exposing anything. The real values live outside the repository entirely.

Inject at runtime

Secrets should reach the application at run time, not be baked into the build. Common mechanisms are environment variables injected by the platform, mounted secret files, or a dedicated secrets manager the app reads at startup.

This keeps the build artefact non-sensitive and lets different environments supply different credentials without rebuilding. Be careful not to undo it by accident: do not print secrets in logs, error messages, or debug output, and redact them in anything that gets captured. A secret that is correctly stored but then echoed into a log line is no longer a secret. Treat every output channel as potentially readable by someone who should not see the value.

Rotation and blast radius

Assume any secret might eventually leak and design so that it is survivable. Two practices matter most: rotation and least privilege.

Rotation means changing credentials periodically and being able to do so quickly — ideally supporting two valid credentials briefly so you can swap without downtime. Least privilege means each credential can do only what it needs; a key scoped to read one resource cannot be used to wreck everything. Together they shrink the blast radius: a leak is contained to a narrow scope and can be revoked fast. Plan rotation before you need it, because doing it under incident pressure is far harder. See environment configuration for where these values are wired in.