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
ghCLI, which uses its own auth:gh auth login, or aGH_TOKENin the environment. In GitHub Actions, setGH_TOKENyourself, 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, thenGITHUB_TOKEN. On a GitHub Actions runner of another server,GITHUB_TOKENbelongs 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, thenGITHUB_ENTERPRISE_TOKEN, thenGITHUB_TOKEN. - for the GitHub Enterprise host
GH_HOSTnames:GH_ENTERPRISE_TOKEN, thenGITHUB_ENTERPRISE_TOKEN. A GitHub Enterprise Cloud tenant onghe.comworks the same way, and is read at itsapi.host. - then, for any host, the login
ghstored for it withgh auth login.
- for github.com:
- For gitlab.com merge requests, VCS linkage uses
GITLAB_TOKENwhen it’s set and asks anonymously otherwise. A private project then reportsunauthenticated. - 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 isunauthenticated.
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:- The client’s own variable -
CLAUDE_PROJECT_DIR(Claude Code),CURSOR_PROJECT_DIR(Cursor), orCODEX_PROJECT_DIR(Codex) - set automatically by the host IRONBEE_PROJECT_DIR, an explicit override you can set- The current working directory
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.