Skip to content

Environment Variables

Every environment variable bb reads, what it does, and what happens when it is unset.

Command-line flags take precedence over environment variables, which take precedence over stored configuration. See Config and auth precedence for the full order.

.env files

Before it resolves anything, bb reads .env files and puts what they hold into the environment for that one invocation. A variable the environment already carries is left alone, so exporting a value always wins over a file, and the values never reach any other process.

Which files are read depends on whether you are in a repository:

Where you are Files read
Inside a repository, marked by a .git or a go.mod .env in the working directory and in every parent up to and including that root
Anywhere else .env in the working directory, and nothing above it

When two of them set the same variable, the nearest to the working directory wins. A .env is read for its content only; it is not configuration, and none of the bb configuration keys work in it. Write variable names, as they appear in the tables below:

BITBUCKET_URL=https://bitbucket.example.com
BB_RETRY_COUNT=5

A .env arrives with a clone

It is a file in a repository, so anyone who can open a pull request can add one, and it is read by the next bb command run in that checkout. bb does not hand a stored credential to a host a .env names — a credential is released only for the host it was stored for — but everything else in the file applies. Read the .env in an unfamiliar repository before running bb in it.

bb update does not read .env. It resolves its own settings without going through the configuration layer, so BB_UPDATE_BASE_URL, BB_DISABLE_UPDATE and BB_ALLOW_HTTP_UPDATE are taken from the real environment and from configuration files, never from a .env. A repository cannot redirect where the next bb update fetches a binary from.

bb doctor shows which file every setting came from, naming the .env by path when that is where it was:

bb doctor

Connection

Variable Default Effect
BITBUCKET_URL none Base URL of the Bitbucket Data Center instance, including scheme and any context path — https://bitbucket.example.com or https://example.com/bitbucket.
BITBUCKET_VERSION_TARGET unset Pins the Bitbucket version bb assumes when behaviour differs between releases. Unset means "whatever the server reports". Most operators never set this.
BB_REQUEST_TIMEOUT 20s Per-request HTTP timeout, as a Go duration (45s, 2m). Equivalent flag: --request-timeout.
BB_RETRY_COUNT 2 Retry attempts for transient failures — connection errors, 429, 5xx. 0 disables retrying. Equivalent flag: --retry-count.
BB_RETRY_BACKOFF 250ms Base delay between retries, multiplied by the attempt number. A Retry-After header from the server wins over this. Equivalent flag: --retry-backoff.

Authentication

A token on the command line ends up in your shell history and in the process list, where other users on the machine can read it. BITBUCKET_TOKEN is the answer to that: it keeps the secret out of argv without storing anything on disk, which is what makes it the right choice for CI and containers.

Variable Default Effect
BITBUCKET_TOKEN none Personal access token, sent as a bearer token. Takes precedence over username/password.
BITBUCKET_USERNAME none Username for basic authentication. Falls back to BITBUCKET_USER, then ADMIN_USER.
BITBUCKET_PASSWORD none Password for basic authentication. Falls back to ADMIN_PASSWORD.
BB_REQUIRE_KEYRING unset 1 makes bb refuse to read or write credentials through the plaintext config fallback. Use it where storing a secret unencrypted is not acceptable — see keyring storage.
BB_DISABLE_STORED_CONFIG unset 1 reads neither the stored configuration file nor any stored credential. Workspace configuration (.bb/config.yaml) and system policy still apply. Useful in CI, where a stray config file on a shared runner would otherwise be picked up.
BB_CONFIG_PATH %AppData%\bb\config.yaml, ~/Library/Application Support/bb/config.yaml or ~/.config/bb/config.yaml Path to the stored configuration file. See Two identities on one host.
BB_WORKSPACE_CONFIG_PATH unset Path to the per-workspace configuration file. Unset, bb looks for .bb/config.yaml, searching upward from the working directory and stopping at the repository root.

BITBUCKET_USER, ADMIN_USER and ADMIN_PASSWORD exist because the test harness sets them. They work, but prefer the primary names.

TLS and proxies

Variable Default Effect
BB_CA_FILE unset Path to a PEM bundle of additional trusted CAs. Added to the system trust store, not a replacement for it. Equivalent flag: --ca-file.
BB_CLIENT_CERT unset Path to a PEM-encoded client certificate or certificate chain for mutual TLS (mTLS). Must be set together with BB_CLIENT_KEY. Equivalent flag: --client-cert.
BB_CLIENT_KEY unset Path to a PEM-encoded client private key for mutual TLS (mTLS). Must be set together with BB_CLIENT_CERT. Equivalent flag: --client-key.
BB_INSECURE_SKIP_VERIFY unset true disables TLS certificate verification. Prints a warning on every invocation. Equivalent flag: --insecure-skip-verify.
HTTPS_PROXY / HTTP_PROXY / NO_PROXY unset Standard proxy configuration, honoured for all bb HTTP traffic. Lowercase spellings work too.

See Networks, Proxies and TLS for how these interact, and for the difference between bb's own requests and the git subprocesses it starts.

Repository context

Variable Default Effect
BITBUCKET_PROJECT_KEY TEST Project key used when --repo is omitted and no repository can be inferred from a git remote.
BITBUCKET_REPO_SLUG none Repository slug, used with BITBUCKET_PROJECT_KEY.

BITBUCKET_PROJECT_KEY defaults to TEST

That default is a leftover from the test harness. It means a command with no --repo, no inferable git remote and no BITBUCKET_PROJECT_KEY will address a project literally named TEST rather than telling you the context is missing. If you get a confusing "project does not exist" error, this is usually why. Set BITBUCKET_PROJECT_KEY explicitly, or pass --repo.

Webhook credentials

Variable Default Effect
BB_WEBHOOK_SECRET none Shared secret for webhook create and webhook update, used to sign deliveries. There is no flag that takes it as a value (ADR-047); the alternative is --secret-stdin.
BB_WEBHOOK_PASSWORD none Password for the endpoint's basic authentication, paired with --credentials-username. The alternative is --credentials-password-stdin.

An empty value counts as unset. A --*-stdin flag wins over the variable, and --no-secret / --no-credentials override both — a variable exported for every command must not make removing a credential impossible. Bulk policies name these variables rather than holding a value; see Webhook Secrets.

Interactivity

bb prompts only when a person is there to answer, and decides that in one place (ADR-072). These two variables are how you tell it nobody is.

Variable Default Effect
BB_NO_PROMPT unset Any value other than 0, false or empty turns prompting off for every command in the process. A command that then needs a value it cannot ask for fails naming the flag that would have supplied it, rather than falling back to a default. Equivalent flag: --no-input.
BB_NO_PROMPT_VARS unset Comma-separated names of further variables whose presence also means nobody is watching.

bb already treats CI, DEBIAN_FRONTEND, NONINTERACTIVE, TERM=dumb and a list of coding harnesses as proof that nobody is there. BB_NO_PROMPT_VARS is for the harness it has not heard of: set it once in the environment to the variable that harness does set, instead of waiting for a release or passing --no-input on every call.

export BB_NO_PROMPT_VARS=MY_BUILD_RUNNER,ACME_AGENT

--json suppresses prompting on its own: a machine reading structured output is not a person who can answer a question.

Updates

Variable Default Effect
BB_DISABLE_UPDATE unset 1 or true disables bb update. The command explains that it is disabled and points at your system package manager. Administrative policy can disable it too, and is reported separately.
BB_UPDATE_BASE_URL GitHub releases Base URL the updater fetches manifests and artifacts from, for an internal mirror. The --base-url flag wins over it; it wins over the workspace, stored and system configuration.
BB_ALLOW_HTTP_UPDATE unset 1 or true permits a plain-HTTP release mirror, as bb update --allow-http does for one run; update URLs are otherwise https only. Refused when policy sets allow_http_update: false.

These three are the exception to the .env rule above: bb update reads them from the real environment only.

Update trust is settable from system policy only

BB_UPDATE_TRUSTED_ROOT, BB_UPDATE_SIGNATURE_IDENTITY and BB_ALLOW_UNVERIFIED_UPDATE are deliberately not read from the environment. A variable that could redirect the trust root would let anything able to set a variable in your shell approve its own update. Configure these through system policy instead — see System Policy.

BB_DISABLE_UPDATE and BB_UPDATE_BASE_URL are honoured because neither weakens verification: the first only refuses to update, and an artifact from a mirror still has to pass the same signature check. BB_ALLOW_HTTP_UPDATE weakens the connection rather than the signature check, and policy can refuse it.

Output and diagnostics

Variable Default Effect
BB_LOG_LEVEL error Diagnostic verbosity: error, warn, info, debug. Diagnostics go to stderr, so they never corrupt --json output on stdout. Equivalent flag: --log-level.
BB_LOG_FORMAT text text or jsonl. Equivalent flag: --log-format.
NO_COLOR unset Any value disables coloured output, following no-color.org. Equivalent flag: --no-color.
BB_ERROR_HARVEST unset Path to a file recording every response Bitbucket refuses, with the request that provoked it. Useful when a failure is hard to describe: set it, reproduce the problem once, and attach the file. Unset, nothing is opened.

For a report of what went wrong, --log-level debug --log-format jsonl gives a structured trace worth attaching to an issue. BB_ERROR_HARVEST is the narrower companion: the trace shows what bb did, the harvest file shows exactly what the server sent back.

Bulk operations

Variable Default Effect
BB_BULK_STATUS_DIR bulk-status beside the stored configuration file Where bb bulk writes plan and run state. Set it somewhere durable if you need runs to survive a reboot, or somewhere shared for a team runner.

Development only

These exist for this repository's own test suite. They are not part of the supported interface and may change without notice.

Variable Effect
BB_BLOCK_EXTERNAL_NETWORK 1 makes any HTTP request to a non-loopback host fail immediately. Used so unit tests cannot reach the internet.

See also