Environment Variables

Environment Variables Management

Source of Truth: Doppler

All environment variables are stored in Doppler. Never hardcode secrets or commit them to git.

Four Integration Points

When adding a new environment variable:

1. Doppler

Add to the appropriate Doppler project and environment.

2. GitHub CI Workflow

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

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

Secrets must exist in repository settings → Secrets → Actions first.

3. Frontend VITE_* Variables (Dockerfile + CI Deploy)

Frontend variables prefixed with VITE_ are baked into the web app at build time by Vite. They must be declared in two places:

A) Dockerfile — Add an ARG declaration so Docker receives the value:

ARG VITE_ADMIN_ORGANIZATION_ID=""

B) .github/workflows/ci.yml deploy step — Pass the value as a --build-arg:

- name: Deploy
  run: |
    flyctl deploy --remote-only \
      --build-arg "VITE_ADMIN_ORGANIZATION_ID=${{ secrets.VITE_ADMIN_ORGANIZATION_ID }}"

If either is missing, the variable will be empty in the deployed frontend.

4. Package-Specific turbo.json

CRITICAL: Add to package-specific turbo.json, NOT root.

{
  "extends": ["//"],
  "tasks": {
    "test": {
      "passThroughEnv": ["CLICKHOUSE_URL", "API_KEY"]
    }
  }
}

Checklist: Adding New Environment Variable

• Add to Doppler for all environments
• Add to GitHub Secrets (if used in CI)
• Add to .github/workflows/ci.yml (if used in CI)
• If VITE_*: Add ARG in Dockerfile and --build-arg in CI deploy step
• Add to package-specific turbo.json → passThroughEnv
• Validate tests pass locally and in CI

Debugging Missing Env Vars

Check in order:

1. Doppler: doppler secrets get VAR_NAME
2. Package turbo.json: cat packages/your-package/turbo.json | grep -A 10 passThroughEnv
3. GitHub Secrets: Repository settings → Secrets → Actions

Common Mistakes

❌ Adding to root turbo.json instead of package-specific ❌ Adding a VITE_* var to CI deploy --build-arg but not as ARG in Dockerfile (or vice versa)

Source: obsessiondb/rudel — distributed by TomeVault.