Environment variables and secrets for website owners

The gap between the code and the running site

A repository holds everything about a site except the things that are specific to where it runs and the things that must stay secret. Both are supplied to the site by its host, at build time and at run time, as environment variables. Copy the code to a new host without them and the site builds, then fails the moment it tries to reach a database, sign someone in, send an email or take a payment.

This is by design, and it’s the right design. It just means that “I have the repository” is a necessary step towards portability and not the last one. This guide is the last one.

What an environment variable is

An environment variable is a named value that a program reads from its surroundings rather than from its own code. A website might read DATABASE_URL to find its database and RESEND_API_KEY to send email. The names are chosen by whoever wrote the code; the values are set wherever the code runs. The same code with different values runs against a different database, which is how one repository can serve a test site and a live one.

Two consequences follow. First, the names are in the code, so a developer or coding agent can list what the site expects. Second, the values are not in the code, so they have to be moved separately, and some of them can’t be moved at all, only reissued.

Where they live

• On the host, in the project’s settings. Vercel has an Environment Variables page per project, with separate values for production, preview and development. Netlify has the same under the project’s environment variables. Cloudflare Workers distinguishes plain variables from secrets. This is where the live site’s values are.
• On a developer’s computer, in a file called .env or .env.local in the project folder. Frameworks read it during local development. It is supposed to be excluded from the repository, and usually is.
• Inside an AI builder, in a settings panel that may be called secrets, environment, integrations or connections. A builder that hosts the site holds the values the way a host does.
• At the service that issued them. The value of an API key came from the API’s dashboard. Some services let you see it again there; many show it once and never again.

Why secrets don’t go in the repository

A repository’s history is permanent and is copied whole to every computer and host that clones it. A password committed once is in every copy forever, even after a later commit removes it from the current files. GitHub’s own guidance is that if a secret has been committed, the first step is to revoke or rotate it, not to try to scrub the history. GitHub also scans repositories for known secret formats and can block a push that contains one, which is helpful but not a substitute for keeping them out.

So the rule is: names in the code, values on the host. If you find a file in the repository called .env with real values in it, treat every value in it as exposed and rotate them.

Public values versus secrets

Not every environment variable is secret. Some are deliberately sent to the visitor’s browser, because the code that runs there needs them: a map provider’s public key, an analytics ID, a payment provider’s publishable key, the address of the site itself. Others must never leave the server: database passwords, secret API keys, the key that signs sign-in sessions.

Frameworks mark the public ones by name:

Services follow the same split. A payment provider issues a publishable key, safe in the browser, and a secret key, never in the browser. Supabase issues a publishable key (formerly called the anon key) for the browser and a secret key (formerly service_role) that bypasses every access rule and must stay on the server. If a secret value has ended up in a NEXT_PUBLIC_ or VITE_ variable, it is already public, and it needs rotating.

How to inventory them

1. List the names the code expects. Ask your coding agent, or a developer: “List every environment variable this project reads, and what each one is for.” It can search the code for them in a minute. Many projects also ship a file called .env.example that lists the names with blank values.
2. List the names the host has. Open the host’s environment variables page and write down every name, and which environments it’s set in. Vercel’s command-line tool can write the variables to a local file and Netlify’s can list them, which a developer can do for you; values marked sensitive or secret will be hidden either way.
3. Reconcile the two. A name the code expects but the host lacks is a bug waiting to happen. A name the host has but the code no longer reads is clutter, or a clue about a feature someone removed.
4. For each variable, record four things: the name, what it’s for, which service issued the value, and whether it’s public or secret. Don’t write the secret values themselves into this list; note where they can be read or regenerated.
5. For each issuing service, check whose account it is. A key issued from a developer’s personal account stops working when they close it. The data guide goes through the services one by one.

The usual kinds, and who issues them

Recreating them on another host

1. Create the project on the new host and open its environment variables page.
2. Enter every name from your inventory, in the production environment. Copy the values that are readable and non-sensitive.
3. For values that can’t be read from the old host, go to the issuing service and generate a new one. Enter it on the new host, and keep the old one valid until the move is finished, so the old host keeps working as a rollback.
4. For values tied to the host itself, such as a payment webhook secret or a sign-in callback URL, register the new host’s address with the service and use the new value it gives you.
5. Build and test on the new host’s own address before changing DNS. A missing or wrong variable shows up here, not in front of visitors. The host move guide places this in sequence.
6. Mark secrets as sensitive on the new host where it offers that; Vercel and Netlify both can make a value unreadable after it’s saved.

When to rotate instead of copy

Rotating means issuing a new value and retiring the old one. Do it when:

• The value was ever committed to a repository, pasted into a chat, emailed, or stored in a shared document.
• The value was issued from someone else’s account, and that person is leaving or the account is being closed. Reissue from an account you own.
• A secret has been living in a public variable.
• You can’t read the current value and don’t know who can.
• It’s been a long time and nobody remembers who has seen it.

Rotation is routine at every service: create the new key, update the host, confirm the site works, delete the old key. Some make it one step; Stripe’s rotate action, for instance, issues the replacement and keeps the old key working for up to seven days so you can switch without a gap. The one to plan around is the database password, because every copy of the connection string changes with it. The sign-in secret is the easiest, because nothing external depends on it; changing it just signs everyone out once.

Checklist

Sources

The rules and product behaviour described above were checked against these pages when the guide was last updated. If something here has changed, these are the places to look.

• Environment variables · Next.js
• Env variables and modes · Vite
• Environment variables · Vercel
• Sensitive environment variables · Vercel
• Environment variables overview · Netlify
• Secrets controller · Netlify
• Secrets · Cloudflare Workers
• Removing sensitive data from a repository · GitHub
• About secret scanning · GitHub
• About push protection · GitHub
• vercel env · Vercel CLI
• env · Netlify CLI
• Connect from any application · Neon
• Installation: AUTH_SECRET · Auth.js
• Clerk environment variables · Clerk
• API keys · Twilio SendGrid
• API keys · Supabase
• API keys · Stripe