Skip to content

KB-005: Mastering Vercel Environment Variables

Field Detail
Document ID KB-005
Version 1.0
Date March 2026
Author Gemi (Gemini — Atlantis AI)
Reviewed By Shane Hardin
Applies To All Atlantis Vercel projects
Difficulty Beginner–Intermediate
Est. Time 10 minutes
Related Docs KB-002 — Cloudflare to Vercel DNS Only, KB-006 — Edge vs Serverless, HT-003 — Vercel 502 Fix

1. Overview

Environment variables are how Atlantis securely stores API keys, webhook secrets, and service URLs without hard-coding them into source code. Vercel provides a first-class environment variable system with three deployment scopes, a sensitive flag for extra protection, and CLI tooling for local development.

Getting this wrong is a security risk — secrets exposed in frontend code or committed to GitHub are the most common attack vector for compromised infrastructure. This is also a lesson already learned in the Atlantis stack (see the roofing lead engine security fix in the infrastructure log).

⚠️ NOTE: Never store secrets in index.html, frontend JavaScript, or committed .env files in GitHub. Always use Vercel's environment variable system for all sensitive values.

2. The Three Deployment Scopes

Vercel lets you set different variable values for different stages of your project lifecycle:

Scope When It's Used Atlantis Example
Production The live public site atlantisits.ai, ai.atlantisits.co
Preview Every Pull Request or branch deployment Feature branches before merging to main
Development Local coding via vercel dev Shane's local machine during active development

💡 TIP: Always set critical variables like N8N_WEBHOOK_URL and ATLANTIS_WEBHOOK_SECRET to all three scopes — Production, Preview, and Development. Missing a scope is a common cause of "works locally but breaks in production" bugs.

3. Adding Environment Variables

Via the Vercel Dashboard

  1. Log in to vercel.com
  2. Open your project (e.g., atlantis-ai)
  3. Click Settings → Environment Variables
  4. Click Add New
  5. Enter the variable name and value
  6. Select the scopes (check all three unless intentionally different per environment)
  7. Check the Sensitive box for any secret, API key, or token
  8. Click Save
  9. Redeploy the project — existing deployments do not pick up new variables automatically

Instead of manually copy-pasting .env files, use the CLI to sync cloud variables to your local machine:

# Pull all cloud environment variables into a local .env.local file
vercel env pull

# The .env.local file is git-ignored by default — never commit it

This ensures your local dev environment uses the exact same variables as production — eliminating "it works on my machine" problems.

4. The Sensitive Flag

When adding a variable in the Vercel dashboard, the Sensitive checkbox encrypts the value so it cannot be read back — even by project admins viewing the dashboard.

Setting Behavior Use For
Standard Value visible in dashboard to admins Non-secret config (URLs, feature flags)
Sensitive Value hidden after save — write-only API keys, webhook secrets, tokens, passwords

⚠️ NOTE: Once a Sensitive variable is saved, you cannot view the value — only overwrite it. If you lose the original value, you must generate a new key from the source service and update Vercel.

5. Atlantis Variable Reference

Variable Project Scope Sensitive Description
N8N_WEBHOOK_URL atlantis-ai All No n8n webhook endpoint for Roofing Lead Engine
ATLANTIS_WEBHOOK_SECRET atlantis-ai All ✅ Yes Shared secret for webhook authentication header

💡 TIP: As Atlantis grows new verticals (plumbing, electrical, lawn care), each will have its own webhook URL variable. Use a consistent naming convention: N8N_WEBHOOK_URL_PLUMBING, N8N_WEBHOOK_URL_ELECTRICAL, etc.

6. Key Rules — What to Do When a Secret is Leaked

If an API key or secret is accidentally exposed (e.g., committed to GitHub, visible in browser dev tools):

  1. Immediately rotate the key at the source service (n8n, Twilio, OpenAI, etc.)
  2. Update the variable in Vercel with the new key value
  3. Redeploy the project — environment variables are baked in at build time, a browser refresh does nothing
  4. Audit the GitHub repo — if the secret was committed, remove it from history using git filter-branch or BFG Repo Cleaner
  5. Check Vercel logs for any unauthorized usage during the exposure window

⚠️ NOTE: This already happened once in the Atlantis stack — the roofing lead engine originally called n8n directly from index.html with the webhook secret exposed in browser-side JavaScript. It was fixed by routing all submissions through /api/roofing-lead server-side. Never let it happen again.

7. Troubleshooting

Error / Symptom Cause Fix
Variables missing after redeploy Variables set for wrong scope (e.g., Preview only) Ensure all three scopes are checked — redeploy
"works locally, breaks in production" Local .env has different values than Vercel Run vercel env pull to sync — then compare
Secret visible in browser dev tools Variable used in frontend/client-side code Move to server-side API route — never expose in frontend JS
Variable updated but site still uses old value Vercel deployment not redeployed after update Go to Deployments → Redeploy latest deployment
vercel env pull returns empty Not logged in to Vercel CLI or wrong project linked Run vercel login then vercel link to associate project
Sensitive variable value lost No way to recover — write-only by design Rotate at source service → update Vercel with new value

8. Quick Reference

Item Value
Vercel dashboard vercel.com → Project → Settings → Environment Variables
CLI sync command vercel env pull
Scopes to always set Production + Preview + Development
Sensitive flag Always check for API keys, secrets, tokens
After updating a variable Must redeploy — browser refresh does nothing
Roofing Lead Engine variables N8N_WEBHOOK_URL, ATLANTIS_WEBHOOK_SECRET
Security rule Never use env vars in frontend/client-side JS
Related fix 502 after variable change → see HT-003

Document prepared by Gemi (Gemini — Atlantis AI Automations)

atlantisits.info | KB-005 | v1.0 | March 2026