Environment Variable Governance Workflow
Inventory every variable and its consumers, distinguish config from secrets with different handling, and kill the folklore of which var matters.
Objective
Bring environment variables under control: declared, owned, typed, with secrets routed to a manager and config documented with defaults.
Environment
- A secret manager for credentials
- A config schema or validation layer in apps
- Access to current environment inventories across deploy targets
Steps
1. Inventory variables across environments
Collect every variable set across deploy targets and local scaffolding, deduplicating names and mapping who reads each one.
Expected state: An inventory exists mapping variable to consumers and environments.
2. Separate config from secrets
Classify each variable as non-sensitive configuration (documented, defaulted, safe to commit) or secret (manager-stored, injected, never in files).
Expected state: Every variable carries a class, and no secret remains in plain env files.
3. Declare and validate at boot
Move config into a typed schema validated at startup with defaults, failing fast on missing or malformed values.
Expected state: Apps refuse to start with invalid config, naming the variable and the violation.
4. Route secrets through the manager
Migrate secrets to the manager with injection at deploy time, rotating during the move and revoking the old values.
Expected state: Secrets exist only in the manager; deployments inject them without file persistence.
5. Kill the dead and dangerous
Delete variables no consumer reads, and rename misleading ones, using the inventory as the evidence for each removal.
Expected state: The variable count shrinks to the set with known consumers.
Expected outcome
A variable set that is declared, typed, validated at boot, with secrets manager-scoped and dead variables gone, ending config folklore.
Verification
Boot validation catches an intentionally removed required variable by name; a scan finds zero secrets in plain files; the inventory shows no consumer-less variables.
Env vars are config with no memory
The typical service reads twenty variables, remembers why three exist, and keeps one root credential from 2021. Inventory, classification, boot validation, and manager routing give the configuration a memory and the secrets a vault.
inventory (before): 47 vars across 3 envs
consumers found: 31
no consumer (dead): 11 -> delete
unknown (undocumented): 5 -> investigate
classification:
config (21): LOG_LEVEL, FEATURE_X, POOL_SIZE...
-> typed schema, defaults, boot validation
secret (10): DB_PASSWORD, SMTP_KEY, JWT_SECRET
-> manager + deploy-time injection
boot validation:
Error: POOL_SIZE: expected int >= 1,
received "twenty" (fails fast, names var)
migration: SMTP_KEY rotated on move,
old value revoked (not just abandoned)Boot validation is the documentation that cannot rot
A README table of variables drifts; a schema that validates at startup cannot. The moment POOL_SIZE receives “twenty”, the process refuses to boot and names the offender — documentation enforced by the compiler of reality.
Migrating secrets means rotating them
Moving a secret into a manager while leaving the old value valid in old files creates two live credentials where there was one. Migration is the perfect rotation moment: inject the new, revoke the old, and the copy-pasted past dies with it.