> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bellows.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables and secrets

> Give the runner the values it needs, such as API keys and feature flags, at the organization, workspace or repository level.

Runners start with no knowledge of your private values. Add them in Settings and Bellows injects them into every run.

## Variable or secret

| | Variable | Secret |
| - | - | - |
| Value shown after saving | Yes | No. It shows as `•••••••` |
| Use for | Flags, URLs, regions | API keys, tokens, passwords |
| Edit in `.env` text | Yes | No |

A secret is write-only. Once saved, nobody can read the value back, not even an admin. To change it, type a new value. To keep it, leave the field blank. The State column shows **Set**, **Not set** or **Will replace when saved**.

## Where to set them

Open **Settings**. Each scope has its own page:

| Scope | Settings page | Applies to |
| - | - | - |
| Organization | **Organization** (section "Organization variables") | Every run in your organization |
| Workspace | **Workspace** (section "Workspace variables") | Only the runs you start |
| Repository | **Repositories**, then **Configure** on a repo | Only runs on that repository |

**1. Pick the tab**

Choose **Variables** or **Secrets**. Each tab shows a count.

**2. Add a row**

Click **New variable** or **New secret**, then enter a name and a value.

**3. Save**

Click **Save changes**. Nothing is stored until you do. **Discard changes** drops your edits.

On the Variables tab, **Raw editor** lets you paste `.env` text instead. **List view** switches back.

> [!NOTE]
>
> Saving sends the whole list for that scope. A name you remove from the list is deleted.

## When a name is set in several places

The most specific scope wins:

```text theme={null}
repository  >  workspace  >  organization
```

If `API_URL` is set in the organization and in a repository, runs on that repository get the repository value. Names that appear in only one scope are all kept.

## Limits and name rules

| Rule | Value |
| - | - |
| Entries per scope | 100 (variables and secrets together) |
| Name | Letters, digits and `_`, not starting with a digit. Up to 255 characters |
| Value | Up to 32,768 characters. No line breaks |

These names are reserved and are refused on save:

* `GITHUB_TOKEN` and `GH_TOKEN`. Bellows issues its own GitHub token for each run (see [Connections](https://docs.bellows.cloud/guides/connections.md)).
* Any name starting with `LD_`, plus `GCONV_PATH`, `GLIBC_TUNABLES`, `LOCPATH`, `NLSPATH` and `MALLOC_TRACE`.
* Names Bellows uses internally, such as `WORKDIR`, `BASE_BRANCH`, `RESTORE`, `REVIEW_REF`, and the `BELLOWS_*` and `SUPERVISOR_*` control names. The editor tells you when a name is refused.
* `OPENCODE_CONFIG_CONTENT` and `CLAUDE_CODE_CONFIG_CONTENT`.

## Where the values are available

The values are set in the environment of the runner for each run. That includes your [`setup` command and gates](https://docs.bellows.cloud/guides/configure-repo) and the agent itself. They are not stored on the run's record.

> [!WARNING]
>
> The agent can read every variable and secret in its environment. Only add secrets you are happy for the agent, and any command it runs, to use. Prefer narrowly scoped keys, such as a test-environment key.

> [!TIP]
>
> Put a value at the narrowest scope that needs it. A staging key used by one repo belongs on that repo, not on the organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.