Environment variables are simple to use but easy to mishandle as an application moves from a laptop to staging and production. This guide provides a repeatable workflow for deciding where configuration and secrets should live, separating browser-safe values from server-only credentials, injecting values through CI/CD, validating deployments, and reviewing the setup on a practical monthly or quarterly cadence.
Overview
An environment variable is a named value supplied to an application at runtime or build time. Common examples include an API base URL, database connection string, session secret, payment-provider key, feature flag, or logging level. The value may differ between local development, staging, and production, while the application code remains the same.
The central rule is to treat configuration as environment-specific and secrets as controlled credentials. A local .env file can be convenient for development, but it should not become the production secret store. Production values should normally be managed by the hosting platform, a dedicated secrets manager, or CI/CD tooling with access controls and audit capabilities.
Keep three concerns separate:
- Configuration: Non-sensitive values such as an environment name, public API origin, or log level.
- Secrets: Credentials that grant access, including database passwords, private API keys, signing keys, and tokens.
- Exposure: Whether a value is available only to server code or is deliberately embedded in browser JavaScript.
This distinction matters because a variable can be hidden from source control yet still exposed in a client bundle. Any value sent to a browser should be considered public, regardless of whether it originated in a secret-looking environment file.
What to track
1. Maintain an environment matrix
Create a small inventory that records each variable, its purpose, the environments where it exists, its owner, and whether it is safe for browser exposure. A matrix makes configuration drift visible without copying secret values into documentation.
| Variable | Purpose | Local | Staging | Production | Exposure |
|---|---|---|---|---|---|
APP_ENV | Application mode | development | staging | production | Server or public, if needed |
DATABASE_URL | Database connection | Local database | Staging database | Production database | Server-only |
PUBLIC_API_BASE_URL | Browser API origin | Local API | Staging API | Production API | Browser-safe |
SESSION_SECRET | Session signing | Local secret | Staging secret | Production secret | Server-only |
Document the variable names and expected format, not the actual secret. For example, record that DATABASE_URL must be a complete connection string and that SESSION_SECRET must be present in every deployed environment. Store the matrix alongside the application documentation and update it whenever a variable is added, renamed, or removed.
2. Establish naming conventions
Use names that reveal purpose without exposing sensitive content. Consistent names reduce deployment mistakes and make validation easier. A practical convention is uppercase words separated by underscores, such as DATABASE_URL, LOG_LEVEL, and PAYMENTS_API_KEY.
Frameworks may apply special prefixes to values intended for browser code. For example, a tool may require a particular prefix for public variables. Treat those prefixes as exposure boundaries, not as security controls: the framework may make the value available to client code, but it does not make a credential safe to publish. Check the current behavior of the framework and build tool before changing a prefix or migrating configuration.
3. Separate local files from committed files
Use a committed example file to document required names and a local ignored file for developer-specific values:
# .env.example
APP_ENV=development
DATABASE_URL=
PUBLIC_API_BASE_URL=http://localhost:3000
SESSION_SECRET=
The real .env file should be excluded through .gitignore. Check the repository history as well as the current working tree; removing a secret from the latest commit does not necessarily remove it from earlier commits. If a credential was committed or printed in a shared log, treat it as exposed and rotate it through the provider that issued it.
4. Validate values before the application starts
Failing early is safer than allowing an incomplete deployment to serve traffic. Validate required variables for presence, type, and basic format during application startup or the deployment build. A URL should parse as a URL, a port should be numeric, and a feature flag should accept only documented values such as true or false.
Do not log complete secret values during validation. A useful error can identify the missing variable name and environment while omitting the value itself. Keep validation rules close to the application configuration layer so local development, CI, and production use the same expectations.
5. Track ownership, age, and rotation
For every sensitive credential, record an owner, its purpose, where it is used, and the last rotation date in an access-controlled system. Avoid placing the secret itself in a general-purpose issue tracker or shared document. Prefer separate credentials for local, staging, and production so a test system cannot access production data by accident.
Cadence and checkpoints
Configuration needs both event-driven checks and a recurring review. A monthly review suits frequently changing applications; a quarterly review may be sufficient for a stable service. The exact cadence matters less than assigning an owner and recording the result.
At every change
- When adding a variable, define its purpose, type, owner, exposure, and default policy.
- When adding an environment, create separate values rather than copying production credentials.
- When renaming a variable, update local setup, CI/CD, hosting configuration, tests, and runbooks together.
- When rotating a credential, confirm which deployments and background jobs consume it, then verify the old value is no longer accepted where possible.
- When changing frontend build configuration, inspect the generated bundle to ensure server-only values were not included.
Monthly or quarterly review
- Compare the environment matrix with the variables currently configured in the hosting platform and CI system.
- Look for unused, duplicated, or inconsistently named variables.
- Review access permissions for repositories, deployment systems, hosting projects, and secret stores.
- Check secret age and schedule rotations for credentials without a documented recent review.
- Inspect build, deployment, and application logs for accidental values or overly detailed configuration output.
- Run a staging deployment from a clean build to test that required values are injected rather than inherited from a developer machine.
- Record decisions, unresolved differences, and the next review date.
For scheduled checks, a CI job or task runner can remind the team without putting credentials in the schedule definition. See the Cron Expression Guide for principles behind reliable recurring jobs. For deployment-specific automation, the GitHub Actions Deployment Guide for Node.js Apps provides related workflow context.
How to interpret changes
Configuration differences are not automatically errors. Staging may intentionally use a separate database, a test payment endpoint, or more verbose logging. The question is whether each difference is deliberate, documented, and safe.
Server-side versus browser-safe variables
| Variable type | Typical examples | Where it may live | Review question |
|---|---|---|---|
| Server-only secret | Database password, private API key, signing secret | Server runtime, CI secret store, hosting secret manager | Could a browser request, bundle, log, or error report reveal it? |
| Server configuration | Log level, internal service URL, deployment mode | Server runtime or deployment configuration | Does the value need to be available during build or only at runtime? |
| Browser-safe configuration | Public API origin, feature label, analytics identifier | Frontend build or public runtime configuration | Would publication allow access or authorization it should not grant? |
A common source of confusion is build-time versus runtime configuration. Some frontend applications substitute variables while compiling a bundle, so changing a hosting variable may require a new build. Server applications may read values when the process starts, making a restart or new deployment necessary. Confirm which model your framework and hosting platform use instead of assuming that an edit takes effect immediately.
When a deployment fails, classify the symptom before changing values. A missing-variable error points to injection or naming. A connection refusal may indicate an incorrect host, network rule, or environment-specific service. A browser CORS error can be caused by an incorrect API origin even when the variable exists; the CORS troubleshooting guide covers that related diagnostic path. If a URL contains query parameters, verify encoding rather than manually editing punctuation; the URL Encoder and Decoder Guide can help inspect those values.
Configuration drift is present when two environments differ without a recorded reason, when the matrix no longer matches deployment settings, or when a variable works only because a developer's shell supplies an undocumented fallback. Resolve drift by identifying the intended state, updating the source of truth, and testing a clean deployment.
When to revisit
Revisit this workflow on a monthly or quarterly schedule, and immediately after any event that changes the application's trust boundaries. The most important triggers are a new deployment environment, a framework or build-tool upgrade, a hosting migration, a new third-party integration, a credential rotation, a security incident, or a change from server-rendered to browser-executed code.
Use this short deployment checklist before promoting a release:
- Required variables are listed in the current environment matrix.
- Each environment uses its own intended service endpoints and credentials.
- Secrets are injected through approved runtime, CI, or hosting controls rather than committed files.
- Browser-exposed values are intentionally public and use the framework's documented configuration path.
- Startup validation checks presence and format without printing secret values.
- Build logs, application logs, error reports, and generated bundles have been checked for exposure.
- The deployment has been tested from a clean environment, and the review result has an owner and date.
Keep this checklist with the project rather than relying on memory. When a review finds no changes, record that outcome; a documented no-change review is still evidence that configuration was checked. When it finds a difference, fix the highest-risk issue first: exposed credentials, shared production access, missing validation, and undocumented production-only behavior.
For adjacent deployment debugging, a structured configuration review pairs well with checking API payloads using a JSON formatter and validator, examining token claims with care in a JWT debugging workflow, and monitoring frontend changes through a JavaScript bundle-size review. The goal is not to create more paperwork; it is to make every environment predictable, auditable, and safe to change.