System Policy¶

Settings an administrator applies to a machine, in a file only an administrator can write. Most of them are mandates: a user who sets the same thing through a flag, an environment variable or their own configuration is refused or warned, rather than quietly winning.

Where policy is read from¶

Platform	Sources, in the order they are merged
Linux, macOS	`/etc/bb/config.yaml`
Windows	`%ProgramData%\bb\config.yaml`, then `HKEY_LOCAL_MACHINE\Software\Policies\bb`

Later sources win, so on Windows a registry value overrides the same key in the file. %ProgramData% is resolved through the Windows known-folder API rather than read from the environment, so setting a ProgramData variable cannot redirect where policy comes from.

Keys may sit at the top level of the file, under a policies: mapping, or under policy:. All three are read, in that order, and a later one wins. Every key follows this order, including update_base_url.

policies:
  require_keyring: true
  allowed_hosts:
    - https://bitbucket.example.com
  disable_update: true

Windows registry values¶

Under HKEY_LOCAL_MACHINE\Software\Policies\bb, each key above has a value with a different name and a registry type. The names are not the YAML spellings:

Value name	Type	YAML key
`RequireKeyring`	boolean	`require_keyring`
`AllowedHosts`	`REG_MULTI_SZ`, or a comma-separated `REG_SZ`	`allowed_hosts`
`CAFile`	`REG_SZ`	`ca_file`
`AllowInsecureSkipVerify`	boolean	`allow_insecure_skip_verify`
`DisableUpdate`	boolean	`disable_update`
`UpdateBaseURL`	`REG_SZ`	`update_base_url`
`AllowHTTPUpdate`	boolean	`allow_http_update`
`UpdateTrustedRoot`	`REG_SZ`	`update_trusted_root`
`UpdateTUFURL`	`REG_SZ`	`update_tuf_url`
`UpdateSignatureIdentity`	`REG_SZ`	`update_signature_identity`
`UpdateSignatureIssuer`	`REG_SZ`	`update_signature_issuer`
`AllowUnverifiedUpdate`	boolean	`allow_unverified_update`
`DisableBB`	boolean	`disable_bb`
`DisableMCPServer`	boolean	`disable_mcp_server`
`ReadOnly`	boolean	`read_only`
`MCPElicitationOptIn`	boolean	`mcp_elicitation_opt_in`
`MCPAIDisclosure`	boolean	`mcp_ai_disclosure`

A boolean is a REG_DWORD of 0 or 1, or a REG_SZ. A REG_DWORD other than 0 reads as true. The string form takes the spellings an administrator is likely to write, in any case: true/false, 1/0, yes/no, on/off, enable/disable, enabled/disabled.

A value bb cannot read is not treated as unset. The restrictive side of that control applies until it is corrected — keyring storage mandated, insecure TLS refused, updates disabled, plain-HTTP updates refused, unverified updates refused, bb or its MCP server switched off, bb read-only — and bb doctor reports the value and what is in force meanwhile.

An empty string value is treated as unset, so a REG_SZ left blank does not mandate an empty path or an empty host list.

Group Policy sets these values through bb's administrative template; see Group Policy.

The environment variables a user sets take the same two spellings and no others: BB_ALLOW_HTTP_UPDATE=yes is refused with BB_ALLOW_HTTP_UPDATE must be true or false (or 1 or 0) and the run fails.

mcp_audit_file has no registry value. Mandating where bb ai mcp serve writes its audit trail on Windows needs %ProgramData%\bb\config.yaml.

Check that a policy took effect

bb doctor

Run it on a machine after deploying policy. It needs no host and no network, and its Settings section gives each effective setting with where it came from, naming the registry when that is the answer. A value that does not appear there is one bb did not read — check the value's name and type against the table above.

Keys¶

Key	Type	Effect
`require_keyring`	boolean	Mandate OS keyring storage for credentials and prohibit the plaintext config file fallback.
`allowed_hosts`	list of strings	Permitted Bitbucket instances, written as full URLs or bare hostnames. A host outside the list is refused with exit `3` before any request is made. See the note below on what an entry does and does not constrain.
`ca_file`	string	Path to a PEM CA bundle that `bb` must use.
`allow_insecure_skip_verify`	boolean	When `false`, `--insecure-skip-verify` cannot be enabled.
`disable_update`	boolean	Disable `bb update` machine-wide.
`update_base_url`	string	Base URL of an internal release manifest and asset mirror.
`allow_http_update`	boolean	Whether `bb update` may fetch over plain HTTP. `false` refuses `http://` update URLs and `--allow-http` for every user; `true` permits plain HTTP for every user. See below.
`mcp_audit_file`	string	Mandate where `bb ai mcp serve` writes its JSON Lines audit trail. Accepts a path or the literal `stderr`.
`update_trusted_root`	string	Path to a Sigstore `trusted_root.json`, so release signatures verify without reaching the Sigstore TUF CDN.
`update_tuf_url`	string	Base URL of an internally mirrored Sigstore TUF repository. Mutually exclusive with `update_trusted_root`.
`update_signature_identity`	string	Expected certificate SAN of the release signer, for organisations that re-sign mirrored artifacts.
`update_signature_issuer`	string	Expected OIDC issuer of the release signer.
`allow_unverified_update`	boolean	Permit `bb update` without Sigstore signature verification. A last resort; SHA256 checksum verification still applies.
`disable_bb`	boolean	Switch `bb` off: every command is refused except the few that only explain it. See below.
`disable_mcp_server`	boolean	Refuse `bb ai mcp serve`, so no MCP client can use `bb`; the rest of `bb` keeps working.
`read_only`	boolean	Refuse every command that changes something in Bitbucket, and start `bb ai mcp serve` read-only.
`mcp_elicitation_opt_in`	boolean	Make every `bb ai mcp serve` ask the person in the MCP client before each call of a tool that decides a merge, as `--elicitation-opt-in` does. `false` does not switch asking off.
`mcp_ai_disclosure`	boolean	Decide for every `bb ai mcp serve` whether what an agent writes ends with a line saying an AI agent wrote it. `false` switches the line off for an organisation that cannot allow it; the server then offers no tool that publishes what the agent writes under the person's name at once. `true` requires the line, whatever `--ai-disclosure` says.

allowed_hosts constrains the host, not the port or the path

An entry matches when the whole normalised URL is equal, or when the hostnames match. The second case is what most entries hit, and it ignores scheme, port and context path — so https://bitbucket.example.com in the list also permits https://bitbucket.example.com:9999/anything.

That is usually what an administrator wants, since one Bitbucket instance can be reached several ways. It is worth knowing before treating the list as a defence against a rogue service on the same host.

Switching bb off, or part of it¶

Three keys decide what bb may be used for on a machine. No flag, environment variable or user configuration lifts them.

disable_mcp_server: true refuses bb ai mcp serve, so no MCP client can start bb as its server. Everything else keeps working, bb ai mcp tools included.
read_only: true refuses every command that changes something in Bitbucket, before it sends a request. Reads run, and so does --dry-run, which changes nothing. bb api is decided by its method: GET and HEAD run, and any other method is refused. bb ai mcp serve starts read-only, offering only the tools that read, whatever its flags say. Commands that change only this machine, such as bb auth login or bb completion install, still run.
disable_bb: true refuses every command. What contacts nothing and changes nothing still answers, so a person can find out why: help, --describe, --version, bb doctor, and printing a completion script, which package managers do while they install bb. Shell completion offers nothing, and says why.

A system configuration file bb cannot parse refuses every command in the same way, since the key it cannot read might be one of these. bb doctor still runs and names the file.

policy:
  read_only: true

These keys govern bb, not Bitbucket

They decide what the bb binary does. They do not change what the user's account or token may do, and they do not stop another program using that token: a script, curl, or git push with the credential that bb auth setup-git hands to git. Where the requirement is that a person or an agent cannot change Bitbucket, give them a token with read permissions only. Where it is that bb never runs, block it with the operating system's application control. Every released build of bb honours these keys, a copy a user downloads themselves included; a build from modified source need not.

What a user meets when policy refuses them¶

Policy does not fail silently, and the message names policy as the reason:

A host outside allowed_hosts is refused before any request is sent.
A --ca-file naming a different bundle from the mandated one is an error; omitting it uses the mandated bundle.
BB_REQUIRE_KEYRING=false against require_keyring: true is ignored, and bb prints a warning saying policy mandates keyring storage.
bb update under disable_update exits 3 (authorization) and says to use the system package manager.
--allow-http or BB_ALLOW_HTTP_UPDATE under allow_http_update: false exits 3, and so does an http:// update URL.
A command under disable_bb, bb ai mcp serve under disable_mcp_server, and a command that changes Bitbucket under read_only exit 3, naming the key and the file or registry key that set it. When the refused command is bb ai mcp serve, the MCP client reports that the server did not start.

`update_base_url` is a default, not a mandate¶

It is the one key here a user can override. The updater takes the first of --base-url, BB_UPDATE_BASE_URL, the workspace configuration, the user's stored configuration, and only then policy — so setting it in policy supplies a mirror to anyone who has not chosen one, and does not pin them to it.

Use disable_update: true where the requirement is that a machine never fetches its own binary. Setting update_base_url alone does not achieve that.

Update URLs are https unless someone asks for plain HTTP¶

bb update fetches over https only: the base URL, every asset URL a manifest names, and every redirect along the way. A user permits plain HTTP explicitly, with bb update --allow-http or BB_ALLOW_HTTP_UPDATE=1, and every run that uses it warns on stderr. There is no configuration file key for it, because a workspace file arrives with a cloned repository.

allow_http_update overrides the user in both directions when policy sets it. false refuses the opt-in and every http:// update URL, whatever the user passes. true permits plain HTTP for everyone, for a fleet whose internal mirror has no TLS.

Update trust is settable from policy only¶

update_trusted_root, update_tuf_url, update_signature_identity, update_signature_issuer and allow_unverified_update are read from policy and from nowhere else — there is no flag and no environment variable for any of them, and the names above are ignored if exported.

That asymmetry is deliberate rather than an oversight. These five decide who may vouch for a new bb binary, so a value settable by anything that can write a variable into a shell would let that thing approve its own update.