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

# Bitbucket Cloud from self-hosted Overcut

> Connect Atlassian-hosted Bitbucket Cloud to a self-hosted Overcut deployment using your own OAuth consumer.

Use this path when you run **Overcut on your own infrastructure** and your
Bitbucket is **Atlassian-hosted Bitbucket Cloud** (`bitbucket.org`). Instead of
the managed Forge app, you connect directly with your **own** OAuth consumer.
Each deployment brings its own credentials; there is no shared Overcut Cloud
client.

<Note>
  Not your setup? See [Which setup do I need?](/docs/integrations/bitbucket#which-setup-do-i-need).
  On **Overcut Cloud**, use the [Forge app](/docs/integrations/bitbucket/cloud)
  instead. For on-prem Bitbucket, see [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center).
</Note>

## Prerequisites

* A **Bitbucket Cloud** workspace, with admin access to **Workspace settings ->
  OAuth consumers**
* A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration))

<Warning>
  The Bitbucket account you authorize with **owns every pull request, comment, and
  merge** Overcut performs. Use a dedicated service account (for example
  `overcut-bot`), not your personal admin account. The service account must be a
  workspace member with write access to the target repositories.
</Warning>

## Choose an authorization type

The connect modal has an **Authorization type** toggle:

* **User authorization (3LO)** - the default, covered by the steps below. A
  browser **Authorize** step runs once, signed in as the service account.
  Bitbucket issues a refresh token so the connection survives long-running
  sessions.
* **Service account (2LO)** - no browser consent. Recommended for headless setups
  or when an org policy blocks interactive authorization. See
  [Use a service account (2LO)](#use-a-service-account-2lo).

## Connect with user authorization (3LO)

<Steps>
  <Step title="Create an OAuth consumer in Bitbucket">
    In Bitbucket, go to **Workspace settings -> OAuth consumers -> Add consumer**
    and name it (for example `Overcut`).

    Set the **Callback URL** to your deployment's Overcut callback, exactly:

    ```
    https://<your-overcut-domain>/bitbucket-cloud-auth-app/callback
    ```

    This must match the `BITBUCKET_CLOUD_REDIRECT_URI` server setting character
    for character, and must use **https** (except `http://localhost:<port>` for
    local development).
  </Step>

  <Step title="Leave the consumer non-private">
    Leave **"This is a private consumer" unchecked**. This is required so Bitbucket
    issues a **refresh token**; without it, the connection breaks on long-running
    sessions.
  </Step>

  <Step title="Enable the permissions">
    Enable these permissions on the consumer:

    * **Account:** Read
    * **Repositories:** Read + Write
    * **Pull requests:** Read + Write
    * **Pipelines:** Read
    * **Webhooks:** Read and write (required so Overcut can register webhooks automatically)

    Save, then copy the **Key** (Client ID) and **Secret**.
  </Step>

  <Step title="Connect in Overcut">
    In Overcut, open the git providers list and click the **Bitbucket Cloud
    (self-hosted connect)** tile. Leave the authorization type as **User
    authorization (3LO)**. Enter your **Workspace** slug (for example `acme`) and
    the **Key** and **Secret** from the previous step.

    Make sure your browser session is signed into Bitbucket **as the service
    account**, then click **Authorize**. Overcut verifies workspace access,
    captures the bot identity, and stores the connection.
  </Step>

  <Step title="Add repositories (webhooks are automatic)">
    Add repositories to Overcut as usual. For each registered repository, Overcut
    **automatically registers a webhook** on the Bitbucket repo for pull request,
    push, and commit-status events, signed with a per-repo secret. There is no
    webhook URL to paste. Removing a repository (or disconnecting the workspace)
    removes its webhook.
  </Step>
</Steps>

## Use a service account (2LO)

Use this when you prefer a headless credential over a browser consent, or when an
org policy blocks interactive authorization. 2LO authenticates as the OAuth
consumer itself (no consenting user), so there is no callback and no Authorize
step.

<Steps>
  <Step title="Create a private OAuth consumer">
    In **Workspace settings -> OAuth consumers -> Add consumer**, create a
    **private** consumer (check **"This is a private consumer"**). A callback URL
    is not required for 2LO.

    Enable the same permissions as the 3LO path - **Repositories** (Read +
    Write), **Pull requests** (Read + Write), **Pipelines** (Read), and
    **Webhooks** (Read and write) - then copy the **Key** and **Secret**.

    <Note>
      The 2LO token authenticates as the **OAuth consumer itself** - a
      service-account-style principal, not a human user - so there is no account to
      sign in as and no browser consent. Overcut attributes its actions to the
      consumer and uses that identity for bot-loop prevention. Create the consumer
      in the workspace that owns the target repositories.
    </Note>
  </Step>

  <Step title="Connect in Overcut">
    Open the **Bitbucket Cloud (self-hosted connect)** tile and switch the
    **Authorization type** to **Service account (2LO)**. Enter the **Workspace**
    slug plus the consumer's **Key** and **Secret**, and click **Connect**.

    There is **no callback URL and no browser Authorize step**. The token acts as
    the consumer owner; scopes come from the consumer's configuration. 2LO has no
    refresh token, so Overcut renews by re-requesting.
  </Step>

  <Step title="Add repositories (webhooks are automatic)">
    Webhook registration is identical to the 3LO path - adding a repository
    automatically registers its webhook.
  </Step>
</Steps>

## Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut
deployment.

| Setting                               | Value                                                             | Notes                                                                                   |
| ------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `INTEGRATION_BITBUCKET_CLOUD_ENABLED` | `true`                                                            | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. |
| `BITBUCKET_CLOUD_REDIRECT_URI`        | `https://<your-overcut-domain>/bitbucket-cloud-auth-app/callback` | Must equal the consumer Callback URL exactly (3LO only).                                |
| `DISPATCHER_BASE_URL`                 | `https://<dispatcher-or-app>/hooks`                               | External URL used to build the auto-registered webhook URL.                             |

The per-repo webhook secret is derived from the deployment's `JWT_SECRET` (shared
by the server that registers the hook and the dispatcher that verifies it), so no
separate webhook secret is required.

## Troubleshooting

* **`redirect_uri` mismatch at Authorize**: the consumer Callback URL and `BITBUCKET_CLOUD_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`).
* **"The authorized account cannot access workspace ..." after consent**: the account you authorized with is not a member of the workspace you entered, or the slug is wrong.
* **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account.
* **Auth fails on long sessions ("no refresh token")**: the 3LO consumer was created as a private consumer, so Bitbucket never issued a refresh token. Recreate it with "This is a private consumer" unchecked and reconnect. (A private consumer is correct only for 2LO.)
* **Webhook events never fire**: confirm `DISPATCHER_BASE_URL` is the external URL and the dispatcher has `INTEGRATION_BITBUCKET_CLOUD_ENABLED=true`; check the repo's webhooks in Bitbucket for the auto-registered Overcut hook.

For concepts shared across all Bitbucket setups (pull request operations, webhook
behavior, ticket links), see the [Bitbucket overview](/docs/integrations/bitbucket).