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

# Bitbucket

> Connect your Bitbucket Cloud workspace to Pavo via OAuth 2.0.

This guide walks you through connecting your Bitbucket Cloud workspace to Pavo. By the end, Pavo will be able to read your repositories, code files, and pull requests.

## Prerequisites

* A [Bitbucket Cloud](https://bitbucket.org/) account with access to the workspace you want to connect
* **Workspace admin** privileges (needed to create an OAuth consumer)

## Step 1: Create an OAuth Consumer in Bitbucket

Pavo authenticates using OAuth 2.0, which requires an OAuth consumer registered in your Bitbucket workspace.

1. Log in to Bitbucket and navigate to your workspace.
2. Go to **Settings** (gear icon in the left sidebar) → **OAuth consumers** (under "Apps and features").
3. Click **Add consumer**.
4. Fill in the form:

| Field | Value |
| - | - |
| **Name** | `Pavo Integration` (or any descriptive name) |
| **Callback URL** | `https://<your-company>.pavoai.dev/api/oauth/bitbucket/callback` |
| **This is a private consumer** | Check this box |

5. Under **Permissions**, grant the following scopes:

| Permission | Access Level | Purpose |
| - | - | - |
| **Account** | Read | Verify user identity and connection |
| **Workspace membership** | Read | List workspaces accessible to the user |
| **Repositories** | Read | List and read repository metadata, code files |
| **Pull requests** | Read | Read pull request details and history |

6. Click **Save**.
7. After saving, you will see the **Key** (Client ID) and **Secret** (Client Secret). Copy both values: you will need them in the next step.

## Step 2: Add the Connector in Pavo

Navigate to **Settings → Data sources** and click **Add source**.

<img src="https://mintcdn.com/pavo/vGe790zaTIwJd6da/images/data-sources.png?fit=max&auto=format&n=vGe790zaTIwJd6da&q=85&s=1d12711dfaea5c39e9d347573a94a713" alt="Data sources page" width="2000" height="1203" data-path="images/data-sources.png" />

Select **Bitbucket** from the connector list.

<img src="https://mintcdn.com/pavo/vGe790zaTIwJd6da/images/connector-picker.png?fit=max&auto=format&n=vGe790zaTIwJd6da&q=85&s=40ae6a2f9d2726470220d7ed65678470" alt="Connector picker" width="2000" height="1212" data-path="images/connector-picker.png" />

Enter the **Key** (Client ID) and **Secret** (Client Secret) from Step 1, then click **Connect**.

You will be redirected to Bitbucket's authorization page.
Review the permissions and click **Grant access**. Bitbucket redirects you back to Pavo with an authorization code, which Pavo automatically exchanges for an **access token** and **refresh token**.

<Note>
  The access token expires periodically. Pavo automatically refreshes it using the refresh token: no manual re-authorization is needed unless you revoke the OAuth consumer.
</Note>

## Step 3: Trigger Sync

Once the connector is authorized and saved, click **Sync Now** on the Bitbucket connector. Pavo will begin indexing:

| Resource Type | What gets synced |
| - | - |
| **Repositories** | Repository metadata: name, description, default branch, clone URLs, README |
| **Code files** | File contents from the default branch (text files only, respecting size and binary filters) |
| **Pull requests** | All pull requests (open, merged, declined) with title, description, author, and dates |

Pavo clones repositories via HTTPS to read file contents. It does **not** push any changes or modify your repositories in any way.

Subsequent syncs are incremental: only files that changed since the last sync are reprocessed.

## Bitbucket API Endpoints Used

For transparency, here are the Bitbucket Cloud REST API endpoints Pavo accesses (all read-only):

| Endpoint | Purpose |
| - | - |
| `GET /2.0/user` | Verify connection and user identity |
| `GET /2.0/workspaces` | List workspaces |
| `GET /2.0/repositories/{workspace}` | List repositories |
| `GET /2.0/repositories/{workspace}/{repo}` | Repository metadata |
| `GET /2.0/repositories/{workspace}/{repo}/pullrequests` | Pull request listing |
| HTTPS clone (`x-token-auth`) | Clone repository for code indexing |

## Troubleshooting

### "Failed to connect to Bitbucket"

* Ensure the OAuth consumer is still active in your Bitbucket workspace settings.
* The access token may have expired and the refresh failed. Try disconnecting and re-authorizing through the Pavo UI.
* Verify the Key and Secret you entered match the OAuth consumer in Bitbucket.

### Missing repositories

* Pavo syncs repositories from the **first workspace** associated with your Bitbucket account. If your repos are in a different workspace, ensure the authorizing user has access to that workspace.
* Private repositories require the **Repositories: Read** permission on the OAuth consumer.

### Code files not appearing

* Binary files and files exceeding the size threshold are skipped automatically.
* Only files on the **default branch** are indexed. Feature branches are not included.

### Pull requests incomplete

* Pavo fetches all PR states (open, merged, declined). If PRs are missing, verify the **Pull requests: Read** permission is granted on the OAuth consumer.

## Revoking Access

To disconnect Pavo from your Bitbucket workspace:

1. Go to Bitbucket → Workspace Settings → **OAuth consumers**.
2. Find the `Pavo Integration` consumer.
3. Click **Delete** to permanently revoke access, or remove the consumer's permissions.

Alternatively, individual users can revoke access from their personal Bitbucket settings under **Authorized applications**.