> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket

> Connect Bitbucket Cloud to CloudThinker for repository, pull request, and pipeline context, and to power Review

Connect your Bitbucket workspace to let CloudThinker agents read repositories, pull requests, and failing pipelines — and to run [Review](/guide/code-review/setup) on the repositories you select. Bitbucket authenticates with **OAuth** or an **access token**; both need your workspace slug.

## Prerequisites

* A **Bitbucket Cloud account** with access to the workspace you want CloudThinker to reach.
* Your **workspace slug** — the segment after `bitbucket.org/` in your repository URLs.
* For access tokens: permission to create a workspace, project, or repository access token. Workspace and project tokens require a **Bitbucket Premium** plan; repository tokens are available on the free plan.

## Setup

Navigate to **Connections → Bitbucket** in your CloudThinker workspace, click **Connect**, then pick an authentication method.

<Tabs>
  <Tab title="OAuth">
    <Steps>
      <Step title="Enter your workspace slug">
        Type the **Bitbucket Workspace** slug (e.g. `my-workspace`). The OAuth flow cannot start without it.
      </Step>

      <Step title="Authorize CloudThinker">
        Click **Connect to Bitbucket**, sign in to the Bitbucket account with access to that workspace, and approve access.
      </Step>

      <Step title="Return to CloudThinker">
        After authorization, CloudThinker stores the OAuth tokens and shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Access token">
    <Steps>
      <Step title="Create an access token in Bitbucket">
        Create a token at the scope you need — for example, for a workspace token go to **Workspace → Settings → Access tokens** and click **Create workspace access token**. Grant:

        * **Account**: Read
        * **Repositories**: Read, Write
        * **Pull requests**: Read, Write
        * **Webhooks**: Read and write
        * **Pipelines**: Read, Write

        Copy the generated token.
      </Step>

      <Step title="Enter the connection details">
        In CloudThinker, switch to the access token tab and enter:

        * **Token Type**: **Workspace**, **Project**, or **Repository Access Token**
        * **Bitbucket Workspace**: your workspace slug
        * **Repository Slug** (repository tokens only): the repository the token covers
        * **Access Token**: the token you just created
      </Step>

      <Step title="Validate and connect">
        Click **Validate Token** to confirm access, then click **Connect**. CloudThinker shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  Bitbucket webhooks for Review are registered automatically — no manual webhook configuration is needed.
</Note>

## Connection details

| Field                   | Description                                                      | Example                |
| ----------------------- | ---------------------------------------------------------------- | ---------------------- |
| **Bitbucket Workspace** | Workspace slug from your repository URLs                         | `my-workspace`         |
| **Token Type**          | Workspace, project, or repository access token — token flow only | Workspace Access Token |
| **Access Token**        | The Bitbucket access token — token flow only                     | —                      |
| **OAuth tokens**        | Issued by Bitbucket and stored automatically — OAuth flow only   | —                      |

## Required permissions

* **OAuth** inherits the workspace access of the authorizing Bitbucket account.
* **Access tokens** need Account Read, Repositories Read/Write, Pull requests Read/Write, Webhooks Read and write, and Pipelines Read/Write.
* **Write operations** such as branch and pull request changes additionally require explicit [approval](/guide/approval) in CloudThinker.

<Tip>
  Match the token scope to the job: a repository token covers one repository on any plan, while workspace and project tokens cover many repositories but require a Premium plan.
</Tip>

## Repository access

On top of what your OAuth account or access token can reach, the connection carries a CloudThinker-side repository policy. Open the connection's detail panel and find **Repository access** under **Settings**:

| Mode         | Behavior                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| **All**      | Every repository the credential can reach is listed and readable; new repositories are included automatically |
| **Selected** | Only the repositories you pick are listed and readable; new repositories are excluded until you add them      |

The policy only ever narrows what the credential already grants, and it is separate from choosing which repositories run [Review](/guide/code-review/setup). Switching from **Selected** to **All** and back restores your previous selection.

## Agent capabilities

Once connected, agents can:

| Capability        | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| **Repositories**  | List and inspect the repositories the connection can reach                        |
| **Pull requests** | Review open pull requests, their discussions, and the changes that need attention |
| **Pipelines**     | Investigate failing pipelines                                                     |
| **Changes**       | Branch and pull request changes — **requires approval**                           |

### Verify the connection

```text theme={null}
@alex list the Bitbucket repositories CloudThinker can reach and summarize their open pull requests
```

### Example prompts

```text theme={null}
@alex #report which open pull requests across our Bitbucket workspace are blocked
@alex #recommend a fix for the failing pipeline on the mobile-app repository
@alex #report this week's merged pull requests
```

## Write access

Reads run without approval. Any change to a branch or a pull request is approval-gated: CloudThinker states the effect and the exact inputs, then waits for your confirmation before touching the repository.

## Troubleshooting

<Accordion title="Connect button stays disabled">
  The OAuth flow requires the workspace slug first. Enter the segment after `bitbucket.org/` in your repository URLs, then click **Connect to Bitbucket**.
</Accordion>

<Accordion title="Token validation fails">
  The token is expired, lacks one of the required permissions, or the token type does not match your plan — workspace and project tokens need Bitbucket Premium. Create a new token with the permissions listed above and validate again.
</Accordion>

<Accordion title="Connected, but CloudThinker asks for a workspace slug">
  An OAuth connection without a stored workspace slug cannot resolve your repositories. Enter the slug in the recovery form CloudThinker shows on the connection to finish setup.
</Accordion>

<Accordion title="Agent cannot find an expected repository">
  A repository token reaches one repository, and a project token only that project's repositories. Reconnect with a broader token, or with an account that has access to the missing repository.
</Accordion>

## 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.

- **Scoped tokens** — a repository or project access token limits CloudThinker to exactly the code it should reach.
- **Set expirations** — give tokens an expiration date and rotate them before they lapse.

## Related

<CardGroup cols={2}>
  <Card title="Review Setup" icon="gear" href="/guide/code-review/setup">
    Turn on automated AI code reviews for your Bitbucket repositories
  </Card>

  <Card title="Provider Authentication" icon="key" href="/guide/code-review/provider-auth">
    Authentication details for every Review provider
  </Card>
</CardGroup>