Fundamentals2 min read
Environment variables vs. secrets: what is the difference?
Environment variables are a way to deliver configuration. Secrets are a kind of value that needs protection. Here is how the two overlap and why it matters.
By the Keel team
The short answer: an environment variable is a delivery mechanism, and a secret is a sensitivity classification. A secret is often delivered as an environment variable, but plenty of environment variables are not secrets, and secrets do not have to be environment variables.
Environment variables
An environment variable is a named string provided to a process by its surroundings. The twelve-factor app methodology recommends storing configuration this way because it keeps config out of code and lets the same build run in different environments.
NODE_ENV=production
PORT=8080
LOG_LEVEL=info
STRIPE_SECRET_KEY=sk_live_...The first three are plain configuration. Anyone can see them without harm. The last one is a secret that happens to travel the same way.
Secrets
A secret is any value whose disclosure grants access or causes harm. What matters is how it must be handled: encrypted at rest, restricted to those who need it, kept out of logs and version control, and replaceable when exposed.
Why the distinction matters
- Different handling.
LOG_LEVELcan live in a config file in the repository.DATABASE_URLwith a password cannot. - Different visibility. Environment variables are visible to the process and its children, and to anyone who can inspect the process or container. Treat them as readable by everything running as that user.
- Different frontend rules. Variables with a public prefix such as
NEXT_PUBLIC_orVITE_are inlined into browser bundles. A secret placed there is public.
Where environment-variable delivery leaks
Environment variables are convenient, but they are not a vault. Common leak paths include crash reports that dump the environment, debug endpoints that print process.env, docker inspect output, build arguments recorded in image history, and child processes that inherit variables they do not need.
A practical rule
Classify each variable. Non-sensitive configuration can be committed or kept in plain config. Sensitive values belong in a store with access control, injected at deploy or run time. Keel keeps both side by side per environment, so you can manage environment variables across environments while treating secret values with the care they need.
Related reading
- What is secrets management? A practical guide for developersSecrets management is how you store, distribute, and control access to credentials such as API keys and database passwords. Here is what it covers and where to start.
- How to manage environment variables across development, staging, and productionA workable approach to keeping environment variables consistent and separate across development, staging, and production without copying files around.
- How to keep secrets out of Git repositoriesPrevent API keys and passwords from reaching Git with ignore rules, scanners, and push protection, and learn the correct cleanup order if one gets committed.
- Environment variablesSeparate Development, Staging, and Production values, with .env import and export.
- Secrets managementOne encrypted place for API keys, tokens, and credentials, organised by project and environment.