Skip to content

ADR-100: Administrative policy can switch bb off, switch its MCP server off, or make it read-only

Three policy keys restrict what bb may be used for. They are read, like all policy, from the system configuration and the Windows registry alone (ADR-058). disable_mcp_server refuses bb ai mcp serve. read_only refuses every command that changes Bitbucket before it sends a request: --dry-run still runs, bb api decides by its method and sends only GET and HEAD, bb ai mcp serve starts read-only, and a command that changes only this machine, such as bb auth login, runs. disable_bb refuses every command. Help, --describe, --version, bb doctor and the completion scripts stay under every lever, since they contact nothing and change nothing.

The root's PersistentPreRunE applies the levers to every command, and read_only follows the dry-run classification of ADR-070. A refusal is KindAuthorization and names the key and the source that set it. A system configuration bb cannot read refuses whatever the levers could, and a registry value bb cannot read switches its lever on (ADR-058).

Classify a new command in dryrun.go: read_only follows the classification, and TestReadOnlyCoversEveryCommandThatChangesBitbucket holds it. Give a lever no flag, environment variable or user configuration key. Add a command to unrefusable only when it contacts nothing and changes nothing. Do not describe the levers as an access control: they govern bb, not the token.

Whether bb, or an agent working through it, may be used on a machine is the organisation's decision, and ADR-058 puts such decisions with the administrator, beyond the user's reach. One check at the root covers a command added later, because every command is classified. Help and doctor stay so a refused person can find out why, and the completion scripts because a package manager prints one while installing bb. A token with read permissions is what holds against a shell; the levers say what bb is for.

Not chosen

  • A check in each command that changes Bitbucket: A command added later would be missed. The classification is exhaustive, and tested.
  • Refuse bb ai mcp serve under read_only: A read-only server is what the policy allows. Refusing it takes the reads away too.
  • Refuse bb api under read_only: Scripts use its reads. Its method is all bb api knows about a request, so the method decides.
  • Refuse help, --describe and the completion scripts under disable_bb: They contact nothing. Refusing help hides why bb refuses, and refusing the completion script breaks installing and upgrading bb through Homebrew.
  • Refuse the git credential helper under read_only: Git asks it for a fetch and a push alike, and says neither, so refusing it stops reads.