Managing Environment Variables Across Deployment Environments

Modern applications run in multiple environments. The same codebase needs different database connections, logging levels, and API keys in development, staging, and production. This page covers patterns for loading the right config in each environment, validating it, passing it through Docker and CI/CD, and safely rotating secrets.

Environment Lifecycle

Development

Your local machine. Local database, verbose logging, hot reload. Config: .env.development

Staging

Pre-production server. Production-like setup, staging database, sandbox API keys. Config: .env.staging

Production

Live server with real users. Production database, real API keys, minimal logging. Config: .env.production

Environment parity: keep environments as similar as possible. Differences should be config values only, not architecture or code behavior.

Pattern 1: Per-Environment .env Files

# Project structure
.env.development   # NOT committed
.env.staging       # NOT committed
.env.production    # NOT committed
.env.example       # Committed (template)
.env.test          # NOT committed (test DB)

Load by NODE_ENV:

require('dotenv').config({
  path: `.env.${process.env.NODE_ENV || 'development'}`
});

Pattern 2: dotenv-flow (Recommended)

Loads files in cascading order, with later files overriding earlier ones:

npm install dotenv-flow

Load order:

.env (shared defaults)
.env.local (local overrides, not committed)
.env.development (or staging/production/test)
.env.development.local

// app.js
require('dotenv-flow').config();
// Automatically loads the right files based on NODE_ENV

cross-env: Cross-Platform NODE_ENV

Setting NODE_ENV in npm scripts works differently on Windows vs Unix:

Platform	Syntax
Unix/Mac	`NODE_ENV=production node app.js`
Windows CMD	`set NODE_ENV=production && node app.js`
Windows PowerShell	`$env:NODE_ENV="production"; node app.js`

cross-env normalizes this:

npm install --save-dev cross-env

{
  "scripts": {
    "start": "node app.js",
    "dev": "cross-env NODE_ENV=development nodemon app.js",
    "staging": "cross-env NODE_ENV=staging node app.js",
    "start:prod": "cross-env NODE_ENV=production node app.js",
    "test": "cross-env NODE_ENV=test jest"
  }
}

Centralized Config Module

Never scatter process.env throughout your codebase. Create one file that reads, validates, and exports all variables:

// config/index.js
require('dotenv-flow').config();

const required = ['PORT', 'DB_URI', 'JWT_SECRET', 'NODE_ENV'];
const missing = required.filter(k => !process.env[k]);
if (missing.length > 0) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

if (process.env.JWT_SECRET.length < 32) {
  throw new Error('JWT_SECRET must be at least 32 characters');
}

module.exports = {
  port: parseInt(process.env.PORT, 10),
  nodeEnv: process.env.NODE_ENV,
  dbUri: process.env.DB_URI,
  jwtSecret: process.env.JWT_SECRET,
  jwtExpiresIn: process.env.JWT_EXPIRES_IN || '1d',
  isDev: process.env.NODE_ENV === 'development',
  isProd: process.env.NODE_ENV === 'production',
  isTest: process.env.NODE_ENV === 'test',
};

// Anywhere in app
const config = require('./config');
mongoose.connect(config.dbUri);
jwt.sign(payload, config.jwtSecret, { expiresIn: config.jwtExpiresIn });

Never write process.env.JWT_SECRET || 'fallback-secret'. If the env var is unset in production, the app silently falls back to a known/weak default. Validate and fail loudly instead.

Environment Variables in Docker

Dockerfile (default values)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000
CMD ["node", "app.js"]

docker run with —env-file

docker run --env-file .env.production -p 3000:3000 myapp

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env.production
    environment:
      - NODE_ENV=production    # Override specific vars inline
    depends_on:
      - mongodb

  mongodb:
    image: mongo:6
    volumes:
      - mongo_data:/data/db
    env_file:
      - .env.production

volumes:
  mongo_data:

Docker Option	Effect
`env_file`	Load all variables from a file
`environment`	Set specific variables inline (overrides env_file)

GitHub Actions Secrets

Store sensitive values in GitHub: Settings > Secrets and variables > Actions > New repository secret.

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production   # Use environment-specific secrets

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install
        run: npm ci

      - name: Test
        run: npm test
        env:
          NODE_ENV: test
          DB_URI: ${{ secrets.TEST_DB_URI }}
          JWT_SECRET: ${{ secrets.TEST_JWT_SECRET }}

      - name: Deploy
        env:
          DB_URI: ${{ secrets.PROD_DB_URI }}
          JWT_SECRET: ${{ secrets.PROD_JWT_SECRET }}
        run: npm run deploy

Secret Rotation: Zero-Downtime Process

Generate new secret

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Update in secret store

Add the new secret to GitHub Actions secrets, Heroku Config Vars, or your secret manager.

Redeploy the application

Restart the app so it picks up the new value.

Verify new secret works

Run health checks. Test authenticated endpoints.

Revoke the old secret

Only disable the old credential AFTER confirming the new one is active.

Monitoring for Leaked Secrets

git-secrets (Pre-commit hook)

# macOS
brew install git-secrets

# Setup in repo
cd my-project
git-secrets --install
git-secrets --register-aws

# Scan entire history
git-secrets --scan-history

GitHub Secret Scanning

Enable in repository settings. GitHub automatically scans every commit and pull request for known secret patterns (AWS keys, GitHub tokens, etc.).

Emergency: Secret Found in Git History

If you discover a secret was committed:

Rotate the secret immediately (generate new, update everywhere)
Use git filter-repo or BFG Repo Cleaner to remove from history
Force-push the cleaned history
Notify all team members to re-clone the repo

Simply deleting the file and committing “remove secrets” does NOT remove the secret from git history. Anyone can still run git log -p to see it. Always rotate first, then clean history.

Key Terms

Term	Definition
Environment parity	Development and production are as similar as possible, differing only in config
Config module	Single file that reads, validates, and exports all env vars
Secret rotation	Replacing old credentials with new ones to limit exposure window
cross-env	Package that sets env vars in npm scripts for Windows + Unix compatibility
CI/CD secrets	Encrypted variables injected into build pipelines by platforms like GitHub Actions
dotenv-flow	dotenv extension that loads multiple .env files in a cascading order

Common Mistakes

Scattering process.env throughout the codebase

When process.env.X appears in 50 files, refactoring and testing become painful. Use a config module: one place to change, mock, and validate.

Committing .env.production to git

Every .env.* file with real secrets must be in .gitignore. Only .env.example is safe to commit.

Using the same secrets across all environments

Development and production must have separate credentials. If a developer’s laptop is compromised, you don’t want production credentials exposed.

No validation at startup

If DB_URI is undefined, your app might start successfully and crash only when the first database query runs. Validate all required vars before the server starts.

Encryption & Libraries

Auth & Access Control

Environment Variables

Environment Lifecycle

Pattern 1: Per-Environment .env Files

Pattern 2: dotenv-flow (Recommended)

cross-env: Cross-Platform NODE_ENV

Centralized Config Module

Environment Variables in Docker

Dockerfile (default values)

docker run with —env-file

docker-compose.yml

GitHub Actions Secrets

Secret Rotation: Zero-Downtime Process

Monitoring for Leaked Secrets

git-secrets (Pre-commit hook)

GitHub Secret Scanning

Emergency: Secret Found in Git History

Key Terms

Common Mistakes

​Environment Lifecycle

​Pattern 1: Per-Environment .env Files

​Pattern 2: dotenv-flow (Recommended)

​cross-env: Cross-Platform NODE_ENV

​Centralized Config Module

​Environment Variables in Docker

​Dockerfile (default values)

​docker run with —env-file

​docker-compose.yml

​GitHub Actions Secrets

​Secret Rotation: Zero-Downtime Process

​Monitoring for Leaked Secrets

​git-secrets (Pre-commit hook)

​GitHub Secret Scanning

​Emergency: Secret Found in Git History

​Key Terms

​Common Mistakes

Environment Lifecycle

Pattern 1: Per-Environment .env Files

Pattern 2: dotenv-flow (Recommended)

cross-env: Cross-Platform NODE_ENV

Centralized Config Module

Environment Variables in Docker

Dockerfile (default values)

docker run with —env-file

docker-compose.yml

GitHub Actions Secrets

Secret Rotation: Zero-Downtime Process

Monitoring for Leaked Secrets

git-secrets (Pre-commit hook)

GitHub Secret Scanning

Emergency: Secret Found in Git History

Key Terms

Common Mistakes