environment-variables

name	environment-variables
description	Environment variable management patterns. CRITICAL use when adding new environment variables (secrets, API keys, config), debugging "X not defined" or missing env var errors, tests passing locally but failing in CI, Turborepo not passing env vars to tasks, or troubleshooting deployment configuration errors.
allowed-tools	["Read","Edit","Grep","Glob","Bash"]

Environment Variables Management

Source of Truth

.env.example documents the variables supported by the public repo. Contributors put local values in an untracked .env file or export them in the current shell. Never hardcode secrets or commit real values.

The core team injects hosted-service values through a private secrets manager. Hosted-service configuration and operations are intentionally outside this repo.

Four Integration Points

When adding a new environment variable:

1. Contributor Environment

Add the variable with a safe placeholder and description to .env.example. Contributors set the real value in .env or their shell.

2. GitHub CI Workflow

Map from GitHub Secrets in .github/workflows/ci.yml:

jobs:
  test:
    env:
      CLICKHOUSE_URL: ${{ secrets.CLICKHOUSE_URL }}
      API_KEY: ${{