Environment variables and secrets

Environment variables hold settings and keys your site's build reads: an API address, a CMS token, an analytics ID. You keep them in Zeloxa instead of in your code, so they never end up in your repository.

Each variable is for Production, Preview or both, so previews of other branches never have to see your production keys. See Production and Preview.

They are used when Zeloxa builds your site from GitHub. Uploads and the CLI publish files you built on your own computer, so there Zeloxa has nothing to pass them to: set them on that computer (or in your CI) instead. See Deploy your first site.

Add a variable #

1. Open your project in Hosting and choose the Settings tab.
2. Scroll to Environment variables.
3. Type the Key, for example PUBLIC_API_URL.
4. Type the Value.
5. Under Environments, choose Production, Preview or both. Both are ticked by default. See Production and Preview.
6. Choose whether it is a Secret (hidden after saving). This box is ticked by default. Untick it for values that are not sensitive, so you can read them later.
7. Choose where it is available: Build, Runtime (full-stack apps), or both. Both are ticked by default. See Build and runtime.
8. Choose Save.

What you'll see: the variable in the list, with a Production and/or Preview badge, a Secret badge if it is one, and a note such as "Production variables changed. Redeploy so the live site picks them up."

Rules for keys:

• Letters, digits and underscores only, starting with a letter or an underscore, up to 128 characters. Keys are case-sensitive.
• These names are set by Zeloxa and cannot be used: CI, PATH, HOME, PWD, SHELL, USER, HOSTNAME, and anything starting with ZELOXA_.
• Each key can exist once per environment: once for Production and once for Preview, or once for both. To change a value, edit the existing variable.

A value can be up to 32 KB. A project can have up to 100 variables.

Paste a .env file #

Have a .env file already? Add all of it at once.

1. In Environment variables, choose Paste a .env file instead.
2. Paste the contents into .env contents.
3. Choose the Environments, Secret and the targets. They apply to every line you pasted.
4. Choose Import variables.

How the text is read:

• One KEY=value per line. A leading export is allowed.
• Blank lines and lines starting with # are ignored.
• One pair of matching quotes around a value is removed: NAME="My Shop" saves My Shop.
• Values that span several lines are not supported. Add those one at a time.

A key that already exists for a chosen environment is not overwritten. You see an error such as "API_URL: API_URL already exists for Production. Edit it instead." for that line, and every other line is still added. To import a separate set of values for previews, paste your preview .env with only Preview ticked, after importing the production one with only Production ticked.

Secrets #

A secret is write-only. Once saved, nobody can read its value again: not in the dashboard, not through the API and not in build logs.

• In the list, a secret shows as •••••••• (hidden). To change it, choose Replace value and type the new one.
• A secret cannot be turned back into a plain variable. To make it readable again, delete it and add it again unticked.
• A plain variable is hidden in the list too. Choose Show to read it and Edit to change it.
• Values are encrypted before they are stored.

Secrets are masked in build logs. If your build prints a secret's value, the log shows *** instead. Values shorter than 4 characters cannot be masked, so do not use very short values as secrets.

What your build puts in your files is public. A static site is files anyone can download. If your build copies a value into the site, for example through a PUBLIC_, VITE_ or NEXT_PUBLIC_ variable, every visitor can read it, secret or not. Only give the build values that are safe to publish, or that it uses without writing them into the output.

Build and runtime #

Each variable has one or both targets:

A variable with only one target shows a Build only or Runtime only badge.

Production and Preview #

Every build is either production (a push to your production branch, a redeploy, a deploy hook on that branch) or a preview (any other branch or pull request; see previews). A variable reaches a build only if it is for that build's environment:

Anyone who can push a branch to your repository can start a preview build, and a build can print or send anything it is given. Keep production-only secrets, such as a live payment key or a production database password, set to Production only, and give previews a test key instead.

Variables created before environments existed apply to both, exactly as they did before. Nothing changes for them until you edit them.

A different value for previews #

To keep the same key with a different value for previews, for example a test API key:

1. Find the variable in the list. It shows Production and Preview badges.
2. Choose Use a different value for Preview.
3. Type the preview value and choose Save Preview value.

What you'll see: two rows with the same key: one with a Production badge and its current value, one with a Preview badge and the new value.

For a variable that is already for one environment only, the same place offers Add a Preview value (or Add a Production value).

Change a variable's environments #

Choose Edit, change the Environments boxes, and choose Save. You can leave the value empty to keep the current one. If the other environment already has its own row for that key, you see an error such as "API_URL already exists for Preview." Delete or change that row first.

See one environment #

Use All, Production or Preview above the list to show only the variables a build of that environment gets.

Apply changes: redeploy #

Changing, adding or deleting a variable does not change the live site or an existing preview. Changes apply to the next deployment of that environment.

1. After saving, choose Redeploy from Git in the note at the top of the section. It opens the project's Git tab.
2. Choose Deploy now.

What you'll see: a new build starts. Its log has a line such as "3 environment variables from project settings." When it finishes, the site uses the new values.

Pushing a new commit, or calling a deploy hook, works too. A Preview change is used by the next build of each preview: push to the branch or pull request again.

Pull requests from forks are never built, so outside contributors cannot read your variables through a preview.

Built-in variables #

Every build from GitHub also gets these. You cannot override them.

For example, to show the commit in your site's footer, read ZELOXA_GIT_COMMIT_SHA in your build and write its first 7 characters into the page. To point canonical links and social previews at the right address, read ZELOXA_URL. To show a "Preview" banner, check whether ZELOXA_ENV is preview.

Delete a variable #

Choose Delete next to it. A confirmation appears under the variable ("Delete API_URL (Production and Preview)?"); choose Delete variable. Like any change, it applies from the next build of that environment; deployments already made are not affected.