Vercel Preview Deployments and Environment Variables

Push to a non-production branch and Vercel automatically spins up a preview deployment. Convenient, but preview deployments silently inherit all Production environment variables unless you explicitly configure overrides. This means database credentials, API keys, and third-party secrets leak into preview environments where anyone with the deployment URL can access them.

The Default Behavior: Inheritance

Vercel's environment variable system works on inheritance by default. When you create an environment variable in the Production environment, it cascades down to Preview and Development environments. This design assumption: preview deployments are testing environments that should mirror production as closely as possible.

But this assumption breaks when secrets shouldn't be accessible outside production. Preview deployment URLs are publicly accessible (unless protected by password). Anyone who discovers a preview URL gets access to environment variables through process.env—a major security hole if those secrets include production database credentials or API keys.

Environment Variable Scopes

Vercel provides three scopes for environment variables:

• Production: Only applies to deployments on your production branch (default: main)
• Preview: Applies to all preview deployments (non-production branches)
• Development: Only applies to local development when using vercel env pull

The catch: when you set a variable in Production, it automatically appears in Preview unless you create a separate Preview-specific variable with the same name. This shadowing behavior is poorly documented and often overlooked.

The Preview Override Pattern

Secure preview deployments use explicit overrides for sensitive variables. Create Preview-specific versions of secrets that either:

1. Use mock/staging credentials for third-party services
2. Use placeholder values that trigger graceful degradation
3. Set empty strings to disable functionality that requires production secrets

# Production environment (inherited by Preview by default)
DATABASE_URL=postgres://production-db.example.com:5432/app
STRIPE_SECRET_KEY=sk_live_51M...

# Preview environment (explicit override)
DATABASE_URL=postgres://staging-db.example.com:5432/app
STRIPE_SECRET_KEY=sk_test_51M...

When Preview has an environment variable with the same name as Production, the Preview value takes precedence. This explicit override ensures preview deployments use safer credentials.

Branch-Specific Variables

For more granular control, configure environment variables per-branch using Custom Environments. This allows different teams or features to use isolated test databases and services:

// vercel.json
{
  "env": {
    "feature-auth": {
      "DATABASE_URL": "postgres://feature-auth-db.example.com"
    },
    "feature-payments": {
      "DATABASE_URL": "postgres://feature-payments-db.example.com"
    }
  }
}

Custom environments are particularly useful for long-lived feature branches where multiple developers need persistent test data without stepping on each other's toes.

Sensitive Environment Variables

Vercel offers sensitive environment variables to protect secrets in logs and error tracking. Enable this at the team level to automatically mark all new Production and Preview variables as sensitive:

# Settings → Environment Variables → Variable Policy
# Enable: "Make all new variables sensitive"

Sensitive variables are redacted in Vercel logs, not displayed in deployment details, and excluded from error tracking integrations like Sentry. This is defense in depth—not a substitute for proper environment scoping.

Common Pitfalls

Pitfall 1: Assuming Preview uses .env.local

Preview deployments ignore .env.local files. Environment variables must be configured through the Vercel dashboard or CLI. Local development files only work with vercel dev and vercel build locally.

Pitfall 2: Using .env in Git

Never commit .env files to Git. They're loaded into builds and expose secrets in deployment artifacts. Use Vercel environment variables exclusively for sensitive data.

Pitfall 3: Forgetting to Redeploy

Changing environment variables doesn't update existing preview deployments automatically. Push a new commit or manually redeploy to apply new variable values. This trips up teams expecting hot-reload behavior for configuration changes.

Best Practices

• Audit preview URLs regularly for leaked secrets before sharing with external stakeholders
• Use branch protection rules to prevent accidental deployments to production from feature branches
• Enable skew protection to prevent version mismatches between client and server in preview deployments
• Rotate secrets immediately if a preview URL is accidentally exposed externally
• Document environment variable requirements in README files with expected values for different environments

Preview deployments are powerful for testing, but their default behavior creates security vulnerabilities. Configure explicit overrides, use sensitive variable flags, and audit regularly to keep your secrets safe while maintaining the convenience of instant preview deployments.