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

# Bitbucket Repos, Pull Requests, and Pipelines

> Work with Bitbucket Cloud repositories, pull requests, issues, branches, and Pipelines through the gateway. Connect with your own Bitbucket OAuth consumer.

## Overview

OneCLI connects AI agents to [Bitbucket Cloud](https://bitbucket.org) through OAuth. Agents can read repositories, clone and push over HTTPS, open and comment on pull requests, work with issues and branches, and read Pipelines runs. The gateway signs every request, API calls and `git` alike, so your agent never sees the token.

Bitbucket uses **your own Bitbucket OAuth consumer**. It is separate from the Atlassian app behind [Jira](https://onecli.sh/docs/integrations/jira.md) and [Confluence](https://onecli.sh/docs/integrations/confluence.md): Bitbucket Cloud registers consumers inside a Bitbucket workspace, not in the Atlassian developer console. Setup takes about five minutes, once.

## Connect Bitbucket

**1. Create a Bitbucket OAuth consumer**

In Bitbucket, open your workspace, then **Settings** (the gear) > **Workspace settings** > **Apps and features** > **OAuth consumers**, and click **Create OAuth client** (older workspaces show **Add consumer**). Name it `OneCLI`.

**2. Set the grant type and callback URL**

On the **Authorization** tab, tick **Authorization code**, then **Refresh token**. Leave **Client credentials** off.

In OneCLI, open **Connections** > **Bitbucket** > **Custom credentials** and copy the **Redirect URI**. Paste it into **Callback URLs** in Bitbucket.

**3. Choose the scopes**

On the **Scopes** tab, tick:

| Area | Scope |
| - | - |
| **Account** | Read |
| **Workspace membership** | Read |
| **Projects** | Read |
| **Repositories** | Read, Write |
| **Pull requests** | Read, Write |
| **Issues** | Read, Write |
| **Pipelines** | Read |

Leave every **Admin** and **Delete** scope, and **Webhooks**, off. Bitbucket fixes scopes on the consumer, so every account connected through it gets exactly these.

**4. Add your credentials and connect**

Save the consumer, then copy its **Key** and **Secret** into OneCLI's **Custom credentials** and click **Save credentials**. Click **Connect Bitbucket** and **Accept** on the Atlassian consent screen.

![OneCLI connect window: OneCLI wants to connect to your Bitbucket, with the setup guide link and the Connect to Bitbucket button.](https://mintcdn.com/chartdbinc/SaEJU23WSeo4RiRe/images/integrations/bitbucket/onecli-connect-bitbucket.png?fit=max\&auto=format\&n=SaEJU23WSeo4RiRe\&q=85\&s=f1ce9d54801d0dcd807f39e52ff9f905)

OneCLI's connect window opens and takes you to Bitbucket.

![Atlassian consent screen: OneCLI is requesting access to your Atlassian account, listing Account, Issues, Pipelines, Projects, Pull requests, Repositories and Workspace membership permissions, the OneCLI callback URL, and the Accept button.](https://mintcdn.com/chartdbinc/SaEJU23WSeo4RiRe/images/integrations/bitbucket/03-provider-consent.png?fit=max\&auto=format\&n=SaEJU23WSeo4RiRe\&q=85\&s=7793ab6c689f7ee58b4ba02cf97598a3)

The consent screen lists exactly the scopes you chose, and the OneCLI callback it returns to.

## What agents can do

| Area | What agents can do |
| - | - |
| **Repositories** | List and read repositories, files, commits, and branches. Clone and push over HTTPS |
| **Pull requests** | List and read pull requests. Open, edit, comment on, merge, and decline them |
| **Issues** | List and read issues. Create and comment on issues |
| **Branches** | Create and delete branches |
| **Pipelines** | Read Pipelines runs and their logs |

Agents clone with a plain URL, for example `git clone https://bitbucket.org/acme/web.git`. Never put a token in the URL: the gateway adds it.

> [!NOTE]
>
> Creating or deleting repositories needs the **Repositories: Admin** scope, which this setup leaves off on purpose. An agent that tries reports the missing scope instead of retrying.

## Controlling access

[Grant](https://onecli.sh/docs/guides/agent-access.md) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked. By default, reads run freely and every write (a push, a new pull request, a comment) asks for approval. Reading **Pipelines variables**, **deploy keys**, or **webhooks** always asks first, because they can hold secrets. Organization [rules](https://onecli.sh/docs/guides/rules.md) add guardrails on top. A blocked request never reaches Bitbucket.

Bitbucket access tokens last two hours and refresh automatically. A connection left unused for three months needs reconnecting, because Bitbucket expires its refresh token.

To disconnect, remove the connection in **Connections** > **Bitbucket**, then revoke OneCLI in Bitbucket under **Personal settings** > **App authorizations**.


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