How to Catch Missing .env Variables and .env.example Drift Before Production Deploy
Originally published at umutgungorr.com . How to stop silent .env vs .env.example configuration drift and undocumented os.getenv calls in CI before a missing environment variable breaks production. Why code that passes locally crashes on deploy Adding a new key to your local .env file while building a feature takes seconds. Forgetting to mirror that key in .env.example and your deployment…
When developers introduce new environment variables to their local .env file during a feature build, it typically takes only seconds. However, if the corresponding key is not added to the .env.example and production environment, the issue remains unnoticed until production traffic triggers a KeyError or returns an empty string. While missing keys are a concern, equally problematic are stale variables that accumulate in templates over time.
New team members struggle to determine which keys are truly necessary, and onboarding processes become slower.
To address this problem, a three-step approach can be implemented in the CI pipeline. Firstly, treat configuration drift as a build failure rather than a passive warning. Utilize the zero-dependency envdoctor-cli package, which compares .env against .env.example and exits non-zero when discrepancies are found. Install it using `pip install envdoctor-cli` and run `envdoctor check --strict` to enforce the .env ↔ .env.example contract. The `envdoctor sync` command can also be used to fill in missing keys.
Secondly, surface undocumented environment variables within the source code. Comparing two env files is not sufficient, as developers may add `os.getenv(NEW_WEBHOOK_SECRET)` without documenting it in either .env or .env.example. Utilize Python AST (Abstract Syntax Tree) analysis to extract actual environment lookups directly from the syntax tree. The `envdoctor audit --format json` command generates a JSON report that highlights these issues.
Lastly, add a five-line gate to the GitHub Actions workflow. This gate runs both template validation and AST auditing on every pull request, ensuring that undocumented environment keys are caught before the branch is merged. The check validates key names only and never transmits secret values. To implement this, create a workflow file named "envdoctor" and specify the jobs in the YAML format.
The job runs on an Ubuntu environment, installs the envdoctor-cli package, and executes the `envdoctor check --strict` and `envdoctor audit` commands. By incorporating these steps into the CI pipeline, developers can catch missing .env variables and .env.example drift issues before they cause production problems.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
