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

# Connect to Bitbucket

> Connect Overcut to Bitbucket so agents can work with repositories and pull requests directly from your workflows.

Connect Overcut to Bitbucket so agents can discover your repositories and work
with code directly. Once connected, agents can clone repositories, open and
review pull requests, and respond to Bitbucket events as part of your workflows.

This page covers the concepts that apply to every Bitbucket connection. **The
exact setup steps depend on where Overcut runs and where your Bitbucket lives** -
pick your path in [Which setup do I need?](#which-setup-do-i-need) below.

## What You Can Do

With Bitbucket connected, Overcut agents can:

* **Access Repositories**: Clone, read, and modify code in your Bitbucket repositories
* **Manage Pull Requests**: Create, review, comment on, and merge pull requests
* **Handle Code Reviews**: Submit approvals, request changes, and add inline comments
* **Code Operations**: Clone repositories, create branches, and perform git operations
* **Webhook Triggers**: Automatically start workflows based on Bitbucket events
* **Repository Configuration**: Configure agent behavior per repository

## Which setup do I need?

Two questions decide your path: **where Overcut runs** and **where your
Bitbucket lives**.

| Where Overcut runs      | Where your Bitbucket lives               | Follow this guide                                                                          |
| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| Overcut Cloud (managed) | Bitbucket Cloud (`bitbucket.org`)        | [Bitbucket Cloud on Overcut Cloud (Forge app)](/docs/integrations/bitbucket/cloud)         |
| Self-hosted Overcut     | Bitbucket Cloud (`bitbucket.org`)        | [Bitbucket Cloud from self-hosted Overcut](/docs/integrations/bitbucket/cloud-self-hosted) |
| Self-hosted Overcut     | Bitbucket Server / Data Center (on-prem) | [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center)                 |

<Note>
  Overcut Cloud connects to **Bitbucket Cloud only** (the managed Forge app is
  Cloud-only). On-prem **Bitbucket Server / Data Center** can only be connected
  from a **self-hosted Overcut** deployment, using your own OAuth credentials on
  your instance.
</Note>

<CardGroup cols={3}>
  <Card title="Bitbucket Cloud on Overcut Cloud" icon="cloud" href="/docs/integrations/bitbucket/cloud">
    Managed Overcut + Bitbucket Cloud. Install the Overcut Forge app. No
    credentials to manage.
  </Card>

  <Card title="Bitbucket Cloud, self-hosted Overcut" icon="server" href="/docs/integrations/bitbucket/cloud-self-hosted">
    Self-hosted Overcut + Bitbucket Cloud. Connect directly with your own OAuth
    consumer (3LO or 2LO). Webhooks register automatically.
  </Card>

  <Card title="Bitbucket Server / Data Center" icon="building" href="/docs/integrations/bitbucket/data-center">
    Self-hosted Overcut + on-prem Bitbucket. Connect with an OAuth application
    link on your instance.
  </Card>
</CardGroup>

## Using Bitbucket in Your Workflows

Once connected, Bitbucket repositories appear as available sources when you:

* Add a **Source** to a workflow
* Configure a **Trigger** that monitors repositories
* Set up **Actions** that work with pull requests

Agents gain secure, permission-scoped access to clone repositories, create
branches, open pull requests, and leave code review comments, without leaving
your existing workflows.

<Note>
  For workflows that need to automatically identify which code repositories are most relevant to issues, consider using the <code>repo.identify</code> action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each issue. Learn more in our <a href="/docs/repositories/repository-mapping">Repository Mapping guide</a>.
</Note>

## Provider-Specific Behaviors

* **Webhooks**: On **Bitbucket Cloud** (self-hosted Overcut), Overcut registers a
  webhook per repository **automatically** when you add the repo - there is
  nothing to paste. On **Bitbucket Server / Data Center**, a project admin
  registers **one project-level webhook** by hand (it is inherited by every repo
  in the project). See each connection guide for details.
* **Ticket links**: Bitbucket does not support typed ticket links through
  Overcut's native integration.

## Permissions

In every setup, Overcut needs read and write access to repositories and pull
requests. **The exact scopes you grant differ by path** (Bitbucket Cloud uses
granular consumer permissions; Bitbucket Server / Data Center uses
repository-level scopes), so they are listed on each connection guide:

* [Bitbucket Cloud on Overcut Cloud (Forge app)](/docs/integrations/bitbucket/cloud)
* [Bitbucket Cloud from self-hosted Overcut](/docs/integrations/bitbucket/cloud-self-hosted)
* [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center)

In all cases, the **account you authorize with owns every pull request, comment,
and merge** Overcut performs, so authorize as a dedicated service account (for
example `overcut-bot`), not your personal admin account.

## Troubleshooting

Path-specific problems (callback URL mismatches, webhook setup, service-account
access) are covered on each connection guide. General checks:

* Ensure the connected account is a workspace/project member with write access to
  the target repositories
* Try disconnecting and reconnecting the integration
* Confirm your Bitbucket instance is accessible from Overcut