Bitbucket connector setup

This page is the setup half — creating the OAuth consumer Bitbucket Cloud needs in a workspace and getting its key and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Bitbucket.

The connector is read-only: workspaces, repositories and pull requests. Bitbucket removed its issue tracker API in 2026, so there is no issue tool. The vendor facts behind this page are in docs/research/connectors/bitbucket.md.

1. Create the OAuth consumer in Bitbucket

1. In Bitbucket Cloud, open the workspace's settings → Apps and features → OAuth consumers and add a consumer. This is your own consumer, not Botseon's.

2. Under Callback URL, paste the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/bitbucket/callback
   

3. Under permissions, tick Account: Read and Pull requests: Read (pull requests read implies repositories read). Nothing else.

4. Save. Bitbucket shows a Key and a Secret — copy both now.

2. Scopes

Bitbucket fixes the permissions on the consumer, not per sign-in, so the authorize request carries no scope and the account is recorded as holding everything the consumer was given (bitbucket:all). Give the consumer only the two permissions above.

3. Enter the app

One command, with the secret on standard input — there is no flag that takes it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug bitbucket \
  --client-id <the consumer key from step 1> \
  --auth-url https://bitbucket.org/site/oauth2/authorize \
  --token-url https://bitbucket.org/site/oauth2/access_token \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug bitbucket says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.