> For the complete documentation index, see [llms.txt](https://prodocs.webhash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prodocs.webhash.com/environment-variables.md).

# Environment Variables

Many websites and apps need configuration values at build time - for example, the URL of an API your app talks to, a public analytics ID, or a feature flag. WebHash Pro lets you store these **environment variables** per repository. They are encrypted when saved, and automatically injected into your project when WebHash Pro builds it.

This page explains how to add, edit, and remove environment variables, how the "leave blank to keep existing" behavior works, and the security details you should know before storing anything sensitive.

{% hint style="info" %}
Environment variables in WebHash Pro are set **per repository**. Each repository you've connected has its own separate list of variables. Choosing a different repository shows a different set.
{% endhint %}

## Opening the Environment Variables page

1. Sign in to your dashboard at <https://pro.webhash.com>.
2. In the left-hand navigation, click **Environment Variables**.
3. At the top of the page, open the **Select Repository** dropdown and choose the repository you want to configure.

Once a repository is selected, any variables already stored for it are loaded into the list.

![Select Repository dropdown open](/files/1O9Ry264mN63PfF7jUw8)

## Adding a variable

1. Select your repository from the **Select Repository** dropdown.
2. Click **Add Variable**. (If the list is empty, you'll see an "Add Variable" button in the center of the empty area as well.)
3. In the **Key** field, type the variable name (for example, `REACT_APP_API_URL`).
4. In the **Value** field, type the value (for example, `https://api.example.com`).
5. Use the **Secret** toggle to mark whether this value should be hidden in the interface (see [Secret vs. non-secret variables](#secret-vs-non-secret-variables) below).
6. Repeat steps 2-5 for any additional variables.
7. Click **Save Variables**.

When the save succeeds, you'll see a "Environment variables saved successfully" confirmation.

![Environment variable row with controls](/files/cPlr9q4L4681kSgyort0)

{% hint style="warning" %}
**Every variable must have a key.** If you click **Save Variables** while any row has an empty **Key**, the save is blocked and you'll be asked to fill it in. You also can't use the **same key twice** for one repository - duplicate keys are rejected.
{% endhint %}

### Naming rules for your build tool

The variable names that actually reach your app depend on the framework you're deploying:

* **React (Create React App):** Variables must start with `REACT_APP_`. In your code they're available as `process.env.REACT_APP_*` - for example, `process.env.REACT_APP_API_URL`.
* **Vite / other static build tools:** Variables are usually read through `import.meta.env` (for example, `import.meta.env.VITE_API_KEY`), following whatever prefix your build tool requires.

{% hint style="info" %}
WebHash Pro stores whatever key/value pairs you give it. Whether a variable is visible inside your app is decided by **your build tool's prefix rules** (like `REACT_APP_` or `VITE_`), not by WebHash Pro. If a value isn't showing up in your built site, double-check the prefix your framework expects.
{% endhint %}

## Editing a variable

To change an existing value:

1. Select the repository.
2. Find the variable in the list. Its **Key** is shown, but the **Value** field is **always empty** when the page loads - your saved values are never sent back to the browser (see [Security](#security--how-your-values-are-protected)).
3. Type the new value into the **Value** field.
4. Click **Save Variables**.

To change only whether a variable is a secret, flip the **Secret** toggle and click **Save Variables** - you can do this without re-entering the value.

### "Leave blank to keep existing" - how it works

This is the most important behavior to understand, and it exists to protect you.

Because WebHash Pro never displays your saved values again, every **Value** field starts out blank - even for variables that already have a stored value. To make this safe, the page follows a simple rule:

* **Leave the Value blank** → the variable keeps its **existing stored value** unchanged. (You can still flip its **Secret** toggle while leaving the value blank.)
* **Type a new Value** → the new value **replaces** the old one.

This means you can safely re-save the page without accidentally wiping values you can no longer see. The **Value** field even shows the placeholder text "Leave blank to keep current value" as a reminder.

{% hint style="warning" %}
The "leave blank to keep existing" rule only applies to variables that **already have a saved value**. If you add a **brand-new variable** and click **Save Variables** with its **Value** left blank, that one variable can't be saved - there's nothing to keep. You'll see a notice that some variables couldn't be saved, listing which key failed and why. Other valid variables in the same save still go through.
{% endhint %}

## Removing a variable

1. Select the repository.
2. Click the **trash icon** at the end of the variable's row to remove it from the list.
3. Click **Save Variables** to apply the change.

## Secret vs. non-secret variables

Each variable has a **Secret** toggle:

* **Secret on:** The value is treated as sensitive. In the interface, its **Value** field is masked (shown as dots), with an **eye icon** you can click to briefly reveal what you've just typed. Secret values are still made available to your build.
* **Secret off:** The value is treated as ordinary configuration and isn't masked in the field.

The **Secret** toggle controls **how the value is displayed in the dashboard**. It does not change whether the value ends up in your published site - see the security note below about client-side bundles.

![Secret variable masked with reveal icon](/files/cPlr9q4L4681kSgyort0)

## When changes take effect

Saving environment variables does **not** rebuild your site on its own.

{% hint style="info" %}
Environment variable changes take effect on your **next deployment**. After saving, trigger a new deployment (or push a commit if you've set up auto-deploy) so the build picks up the new values.
{% endhint %}

During a build, WebHash Pro decrypts your variables and writes them into standard `.env`, `.env.local`, and `.env.production` files at the root of your project, and also passes them to the install and build steps - so your build tool picks them up the same way it would locally.

## Security - how your values are protected

WebHash Pro is built so that your stored values are kept private even from the dashboard itself.

* **Encrypted at rest.** Every value is encrypted using AES-256-GCM authenticated encryption before it's stored. Values are never saved as plain text.
* **Never displayed again.** Once saved, a value is never sent back to your browser. That's why every **Value** field loads empty and why the "leave blank to keep existing" rule exists.
* **Never logged.** Values are never written to logs. If a stored value can't be decrypted for any reason, the system skips it and records only the variable's **name**, never its contents.
* **Access-checked before use.** When values are decrypted for a build, WebHash Pro first verifies that you still have GitHub access to that repository. If you don't, the request is denied.
* **Excluded from your published site's files.** The temporary `.env` files created during the build are stripped out before your site is uploaded to IPFS, so those raw files are never published.

{% hint style="warning" %}
**Client-side apps expose their variables to the public.** Anything your front-end code reads (such as a `REACT_APP_*` or `VITE_*` value) gets compiled into the JavaScript bundle that ships with your site. Because your site is hosted publicly on IPFS, **anyone can read those values** by inspecting the bundle.

Only put **non-sensitive** configuration or **public** keys in client-side variables. For truly sensitive secrets (private API keys, database credentials, signing keys), use a separate backend service with proper authentication instead of embedding them in a static site.
{% endhint %}

### Limits

* Up to **100 variables** per repository.
* Each value can be up to **10 KB** in size.

## Troubleshooting

* **"All environment variables must have a key."** One of your rows has an empty **Key**. Fill in every key before saving.
* **"Duplicate environment variable keys are not allowed."** You've used the same key twice for this repository. Each key must be unique.
* **"Some environment variables could not be saved."** Usually this means you added a brand-new variable and left its **Value** blank. Enter a value for new variables, then save again. The message lists which key failed.
* **My new value isn't showing up in my site.** Make sure you (1) saved the variable, (2) started a **new deployment** afterward, and (3) used the correct prefix your build tool requires (for example, `REACT_APP_` for Create React App or `VITE_` for Vite).

{% hint style="success" %}
A good workflow: add or update your variables, click **Save Variables**, confirm the success message, then trigger a fresh deployment so the build uses your latest configuration.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://prodocs.webhash.com/environment-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.