Skip to main content
Most configuration lives in config files, but a few settings can be supplied via environment variables, handy for CI runners, ephemeral shells, and secrets you don’t want to commit.

Common

An override set to an empty string counts as unset.
Because these override the files, a merged read (ironbee config get service.apiKey) returns the env value. A layer-scoped read (--project / --global / --local) bypasses env and shows only what’s on disk.

Verification jobs, code reviews and credits

ironbee verify - the cloud verification-job runner - reads two extra overrides of its own, plus the GitHub Actions, GitLab CI or Bitbucket Pipelines context. ironbee review and ironbee credits read the same two overrides, and like verify they also read IRONBEE_API_KEY ahead of the config. An OAuth token still wins over any API key; see Credentials for the full order. ironbee review and ironbee credits read the credential and the endpoints from the environment, the flags, the personal file and the global config only, never from a file inside the checkout. They’re the only commands that read the personal file. See Where the review goes, and as whom.

Issue-tracker credentials

The issue-tracker integrations normally keep their secrets in your global config (~/.ironbee/config.json, written by ironbee integrations <provider> setup). In CI - or anywhere you’d rather source them from a vault - supply them via env instead. Like the collector credentials, these take precedence over every config layer: GitHub, GitLab and Bitbucket need no IronBee credential variable:
  • The GitHub issue tracker runs the gh CLI, which uses its own auth: gh auth login, or a GH_TOKEN in the environment. In GitHub Actions, set GH_TOKEN yourself, for example to ${{ github.token }}.
  • VCS linkage calls the GitHub API only with a token meant for the host it asks, the first one set:
    • for github.com: GH_TOKEN, then GITHUB_TOKEN. On a GitHub Actions runner of another server, GITHUB_TOKEN belongs to that server and isn’t sent to github.com.
    • for the runner’s own server, the host in GITHUB_SERVER_URL: GH_ENTERPRISE_TOKEN, then GITHUB_ENTERPRISE_TOKEN, then GITHUB_TOKEN.
    • for the GitHub Enterprise host GH_HOST names: GH_ENTERPRISE_TOKEN, then GITHUB_ENTERPRISE_TOKEN. A GitHub Enterprise Cloud tenant on ghe.com works the same way, and is read at its api. host.
    • then, for any host, the login gh stored for it with gh auth login.
  • For gitlab.com merge requests, VCS linkage uses GITLAB_TOKEN when it’s set and asks anonymously otherwise. A private project then reports unauthenticated.
  • For bitbucket.org pull requests, VCS linkage uses BITBUCKET_TOKEN, a Bitbucket access token sent as a bearer token. In a Bitbucket Pipelines step, it reads the step’s own pull request with the token when it’s set, and anonymously otherwise, so a private repository needs the token. Anywhere else it needs the token, and without it the status is unauthenticated.
Since CLI 0.49, an environment token goes only to the host it’s meant for: GH_TOKEN to github.com, and GITHUB_TOKEN to the runner’s own server, or to github.com outside a runner. For any other GitHub Enterprise host, name it in GH_HOST and set GH_ENTERPRISE_TOKEN, or run gh auth login for that host.

Config placeholder bridges

Config placeholders let a committed config carry references that resolve from the environment - the way to override a team default per developer or per CI run without editing a file:
The IRONBEE_PARAM_* / IRONBEE_ENV_* prefixes are reserved for placeholder input - the implied prefix means arbitrary environment variables (secrets, tokens) are structurally unreachable from config text. An empty value counts as unset (the reference falls through to its :- default). IronBee’s own operational env vars never use these prefixes.

Project directory resolution

When a hook or command needs to know which project it’s acting on, IronBee resolves the directory in this order:
  1. The client’s own variable - CLAUDE_PROJECT_DIR (Claude Code), CURSOR_PROJECT_DIR (Cursor), or CODEX_PROJECT_DIR (Codex) - set automatically by the host
  2. IRONBEE_PROJECT_DIR, an explicit override you can set
  3. The current working directory
You normally don’t set these yourself; the AI client provides them. IRONBEE_PROJECT_DIR is the escape hatch for scripted or non-standard setups.

Advanced

Rarely needed, mostly for internal wiring and test harnesses:

What’s next?

Configuration

The full config-key reference, the file-based equivalents of these overrides.

Runtime files

Where config and credentials are stored on disk.