Configuration & `.env`¶

Everything that maintainers or users would normally pre-set lives in environment variables. They can be set directly in your shell, in CI variables, or in a .env file at the repo root (or any path you point PULSE_DOTENV at).

A real environment variable always wins over the .env file, so CI overrides are easy.

Search order¶

$PULSE_DOTENV  →  $PWD/.env  →  <repo-root>/.env

The first file that exists is loaded. We don't merge — pick one location.

File format¶

Standard dotenv subset. Comments with #, optional export, optional surrounding quotes:

# A maintainer's setup
PULSE_RELAY_URL=https://pulse-relay.you.workers.dev/submit
PULSE_GITLAB_PROJECT_URL="https://gitlab.com/you/pulse"
export PULSE_SUBMITTER_NAME="Patrik"

We don't depend on python-dotenv. It's a tiny stdlib parser (src/pulse/dotenv.py) so the uvx cold start stays fast.

Reference¶

Maintainer¶

These are the values the project owner sets once.

variable	required	what
`PULSE_RELAY_URL`	for one-click publishing	URL of your deployed Cloudflare Worker — see Maintainer setup. If unset or left as the example placeholder, the TUI falls back to opening the user's browser with a prefilled GitLab issue URL.
`PULSE_GITLAB_PROJECT_URL`	for the browser fallback	URL of the public project where MRs land (this repo). Used only when the relay isn't reachable. Default: `https://gitlab.com/ai-sys0x/pulse`.

User (anyone running benchmarks)¶

variable	what
`PULSE_SUBMITTER_NAME`	Pre-fill the Name input on the Results screen. The TUI Input is still editable. Used by `--headless --publish` when no `--name` flag is passed.
`PULSE_SUBMITTER_EMAIL`	Same, for email.
`PULSE_HEADLESS`	Any non-empty value forces `--headless` without the flag. Useful for scripts where you want headless even in a TTY.
`PULSE_AUTO_PUBLISH`	Any non-empty value enables `--publish` for headless runs. Combine with `PULSE_SUBMITTER_NAME/EMAIL` for fully unattended submissions.
`PULSE_OUT`	Override the run directory (default: `~/.local/share/pulse/runs/<TIMESTAMP>`).
`PULSE_DOTENV`	Path to a non-default `.env` file.

Advanced¶

variable	what
`PULSE_ENABLE_CHROMIUM_BUILD`	Set to `1` to enable the `compile_chromium` benchmark. Off by default because a real Chromium build is hours and ~100 GiB.

Relay (Cloudflare Worker secrets)¶

These live inside the worker and are pushed via wrangler secret put by the GitLab CI deploy job. Their source-of-truth is GitLab CI variables (and your local .env for testing — same names: RELAY_GITLAB_TOKEN, RELAY_GITLAB_PROJECT, etc.). Never commit values to the repo.

worker binding	source CI variable	what
`GITLAB_TOKEN`	`RELAY_GITLAB_TOKEN`	`glpat-…` from the `pulse-relay-worker` service account, `api` scope.
`GITLAB_PROJECT`	`RELAY_GITLAB_PROJECT`	This repo, e.g. `ai-sys0x/pulse`.
`GITLAB_TARGET_BRANCH`	(worker default)	Default branch to merge into. Default: `main`.
`GITLAB_URL`	(worker default)	GitLab host. Default: `https://gitlab.com`.
`PULSE_HMAC_SECRET`	`RELAY_HMAC_SECRET` (optional)	Shared HMAC; locks the relay to your client.
`TURNSTILE_SECRET`	`RELAY_TURNSTILE_SECRET` (optional)	Cloudflare Turnstile site secret.

See docs/maintainer.md for the full deployment + rotation flow.

Templates¶

A complete starter file lives at the repo root: .env.example. Copy it to .env and fill in the bits you care about — every variable is documented inline.

cp .env.example .env

Don't commit .env (it's in .gitignore).

Configuration & .env¶