Bitbucket

Connect Bitbucket Cloud so agents can read repositories, pull requests, and pipelines, and Review can comment on pull requests

Connect Bitbucket and CloudThinker agents can read your repositories, pull requests, and pipelines, and Review can post AI code reviews on pull requests. You sign in with OAuth, or paste a workspace, project, or repository access token. Both methods need your workspace slug.

Prerequisites

• A Bitbucket Cloud account with access to the workspace you want agents to read. The connection talks to bitbucket.org and has no field for a Bitbucket Data Center or Server URL.
• Your workspace slug: the part after bitbucket.org/ in your repository URLs. In bitbucket.org/acme/payments-api, the slug is acme.
• For the token method: admin rights on the workspace, project, or repository where you create the token.
• For Review with OAuth: admin rights on the repositories Review runs on, because Bitbucket only lets repository admins add webhooks.
• The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.

Choose a method

Method	Use it when	Bitbucket plan
OAuth	You want the fastest setup and access that matches your own account	Any
Workspace Access Token	One credential should cover every repository in the workspace	Premium
Project Access Token	Access should stay inside one Bitbucket project	Premium
Repository Access Token	Access should cover exactly one repository	Any, including Free

A workspace holds one Bitbucket connection. To try CloudThinker on several repositories, use a project or workspace token, or OAuth, rather than several repository tokens.

Setup

Open the connection first. In the sidebar, click More → Workspace settings → Connections. On the Builtin Connections tab, search for Bitbucket and click Connect. The dialog opens with two tabs: OAuth and Access Token.

OAuth

1. Enter your workspace slug

   On the OAuth tab, type your slug in Bitbucket workspace (for example acme). Connect to Bitbucket stays disabled until this field has a value.

2. Authorize CloudThinker

   Click Connect to Bitbucket. Sign in as a Bitbucket user who can see the workspace, then approve the request. CloudThinker asks for read and write repository access, API access for webhooks and pull requests, and your account information (username, email).

   Success state: you land back in CloudThinker with Bitbucket Connected! and Bitbucket shows Connected on the Builtin Connections tab.

Access Token

1. Create the token in Bitbucket

   Pick a token type from Choose a method, then open its screen:

   Token type	Where to create it	Button
   Workspace	Workspace → Settings → Access tokens	Create workspace access token
   Project	Project → Project settings → Access tokens	Create project access token
   Repository	Repository → Repository settings → Access tokens	Create Repository Access Token

   Grant the permissions in Required permissions, set an expiration date, and copy the token.

2. Enter the connection details

   On the Access Token tab, pick the Token Type and fill in the fields from Connection details.

3. Validate and connect

   Click Validate Token. CloudThinker shows Token works with the number of repositories the token can see. Then click Connect.

   Success state: CloudThinker shows Connected to Bitbucket and Bitbucket shows Connected on the Builtin Connections tab.

CloudThinker registers the Bitbucket webhook for Review on its own. You don’t add one by hand. Pick the repositories Review runs on in Review setup.

Connection details

OAuth needs only the workspace slug. Bitbucket issues the credentials and CloudThinker stores them.

Field	Description	Example
Token Type	Workspace Access Token, Project Access Token, or Repository Access Token	Workspace Access Token
Bitbucket Workspace	Your workspace slug	acme
Repository slug	Repository tokens only: the repository the token covers	payments-api
Access Token	The token you created in Bitbucket	<your-token>

Required permissions

Method	What decides access
OAuth	Everything the signed-in Bitbucket user can see in the workspace
Access token	The permissions below, limited to the token’s workspace, project, or repository

Every token type needs the same scopes, and all three types offer them:

Scope	Access	Why
Repositories	Write (includes Read)	Read code, and push branches and fix commits through approvals
Pull requests	Write (includes Read)	Read pull requests and post Review comments
Webhooks	Read and write	Register the Review webhook automatically
Pipelines	Write (includes Read)	Pipeline analysis

Access tokens have no issues scope, so agents can’t read Bitbucket’s issue tracker through a token. Connect with OAuth if you need issues.

Review needs the write permissions to register its webhook and post comments. Agent writes still pass through your Rules and Approval mode before anything changes.

Start with a repository token on one repository to try CloudThinker. It works on any plan, and revoking it affects nothing else. Move to a workspace or project token when you roll out wider.

Control access in CloudThinker

Two settings on the connection’s detail panel narrow what agents do. Open More → Workspace settings → Connections, select Bitbucket, and look under Settings.

Setting	Options	What it does
Repository access	All or Selected	All lets agents read every repository the credential reaches, including new ones. Selected limits agents to the repositories you pick, and new repositories stay excluded until you add them. Switching to All and back restores your earlier selection.
Allow writes	On (default) or off	On: agents can propose changes, and your Rules and Approval mode decide each one. Off: agents can only read, and every change is refused.

These settings only narrow what Bitbucket already grants. Choosing which repositories Review runs on is a separate step in Review setup.

Agent capabilities

Reads run without asking. Writes need Allow writes on and pass through your Rules and Approval mode first.

Capability	What agents can do
Repositories	List the repositories the connection reaches and read their code and history
Pull requests	Summarize open pull requests, their reviewers, and discussion
Pipelines	Find failing pipelines and read step logs to explain the failure
Issues	Read issues for triage and delivery context, when the repository uses Bitbucket’s issue tracker (OAuth only)
Changes	Create branches, comment, or open pull requests, each through approvals

Verify the connection

List the Bitbucket repositories you can reach and how many open pull requests each one has

A working connection names your real repositories and counts. If some are missing, check the token type and Repository access.

Example prompts

Which open pull requests in the acme workspace have had no review for more than 3 days?
Why did the latest pipeline on main fail in the payments-api repository?
Summarize the pull requests merged into main across our Bitbucket repositories this week

Troubleshooting

Connect to Bitbucket stays disabled

The OAuth flow needs the workspace slug first. Enter the part after bitbucket.org/ from any repository URL, then click Connect to Bitbucket.

Validate Token fails

The token is expired or revoked, lacks one of the required permissions, or doesn’t match your plan. Workspace and project tokens need Bitbucket Premium. Create a new token with every permission in Required permissions and validate again.

Confirm Bitbucket workspace

This warning appears on an OAuth connection that has no stored workspace slug. Bitbucket no longer lets CloudThinker discover the workspace on its own, so you enter it once. It shows on the connection’s detail panel and in Review → Settings. Click Set workspace, enter the slug, and click Save workspace.

An agent can't find a repository

A repository token reaches one repository, and a project token reaches only that project. Use a workspace token, or sign in with OAuth as a user who can see the repository. Then check that Repository access includes it.

Agents can read but every change is refused

Allow writes is off on the connection, or a Rule blocks the action. Turn on Allow writes under Settings, then check your Rules.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Prefer scoped tokens. A repository or project token keeps CloudThinker inside the code it should see, and revoking it touches nothing else.
• Set an expiration date. Rotate the token before it lapses, or Review and agents lose access on that day. To swap in the new token, open Review → Settings, open the Connection actions menu (⋯) in the Connection section, and click Update token.

Related

Set Up Review

Choose repositories and start AI code reviews on pull requests

Provider Authentication

Compare auth methods across every Git provider