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

# Bitbucket

> Connect Bitbucket Cloud pull requests to AI ROI

## Overview

Connect **Bitbucket Cloud** (`bitbucket.org`) so AI ROI can see the pull requests your developers merge, the commits in them, and your deployments. It works the same way as the [GitHub](https://help.nops.io/integrations/github.md) and [GitLab](https://help.nops.io/integrations/gitlab.md) integrations.

nOps only reads. It never writes to Bitbucket, and it never stores file contents or commit messages. Commit messages are read only to spot AI co-author markers and reverts.

nOps reads:

* **Pull requests:** title, author, branch, when it was opened and merged, and lines changed.
* **Commits in each pull request:** the commit ID and the author's email, including commits squashed away on merge.
* **Files changed:** each file's path and how many lines were added and removed.
* **Deployments:** which merged work reached an environment, when you use Bitbucket Deployments.

> [!NOTE]
>
> This integration targets **Bitbucket Cloud** only. Bitbucket Data Center and Server are not
> supported yet.

## What token do I need?

Bitbucket retired app passwords. Use one of these instead:

| Token | How nOps signs in | Best for |
| - | - | - |
| **API token with scopes** (recommended) | Your Atlassian account **email** plus the token | Any plan. The account must be able to read the workspace's repositories. |
| **Workspace access token** | The token alone (leave email blank) | Bitbucket **Premium**. Not tied to a person. |

Give the token these read scopes:

| Scope | Required | Why |
| - | - | - |
| `read:repository:bitbucket` | Yes | Lists repositories and reads commits and file stats. |
| `read:pullrequest:bitbucket` | Yes | Reads pull requests. The repository scope does not include them. |
| `read:pipeline:bitbucket` | Optional | Reads deployments, for **In production** status. |
| `read:workspace:bitbucket` | Optional | Reads workspace details. |

For a workspace access token, choose the matching read permissions: **Repositories: Read**, **Pull requests: Read**, and optionally **Pipelines: Read**.

> [!NOTE]
>
> Only nOps **admins** and **owners** can connect, re-validate, or disconnect. **Members** see
> **Admin Only** on connectable cards.

## Create the token

### API token with scopes (recommended)

1. Sign in to your Atlassian account and open **Account settings → Security → Create and manage API tokens**.
2. Choose **Create API token with scopes**, name it (for example `nOps AI ROI`), and set an expiry date.
3. Select **Bitbucket** as the app, then select the scopes in the table above.
4. Create the token and copy it. It is shown only once.

### Workspace access token (Premium)

1. In Bitbucket, open your workspace's **Settings → Access tokens**.
2. Create a token with the read permissions above.
3. Copy the token. It is shown only once.

## Connect in nOps

1. Go to **Settings → Integrations** and open **Bitbucket**.
2. Enter your **workspace** ID: the `acme` in `bitbucket.org/acme`.
3. For an API token, enter the **Atlassian account email** that created it. For a workspace access token, leave the email blank.
4. Paste the token and click **Connect**.

nOps checks the token before saving it: it lists the workspace's repositories and reads pull requests from one of them. If a scope is missing, the error says which one to add.

## After connecting

Pull requests appear in AI ROI after the next daily refresh. To have the Clara developer agent record work in your Bitbucket repositories too, add the workspace to the agent's allowlist as `bitbucket.org/<workspace>` in **Settings → Integrations → AI ROI agent → Policy**.

## Related

* [GitHub integration](https://help.nops.io/integrations/github.md)
* [GitLab integration](https://help.nops.io/integrations/gitlab.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.