> ## 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 Server / Data Center

> Connect an on-prem Bitbucket Server or Data Center instance to a self-hosted Overcut deployment using an OAuth application link.

Use this path when you run **Overcut on your own infrastructure** and your
Bitbucket is **self-hosted Bitbucket Server or Data Center** (an on-prem
instance, not `bitbucket.org`). You connect with an **OAuth 2.0 incoming
Application Link** created on your Bitbucket instance. Each deployment uses its
own client 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).
  For Atlassian-hosted Bitbucket Cloud, use the [Forge app](/docs/integrations/bitbucket/cloud)
  (Overcut Cloud) or [direct OAuth](/docs/integrations/bitbucket/cloud-self-hosted)
  (self-hosted Overcut).
</Note>

## How it differs from Bitbucket Cloud

|                 | Bitbucket Server / Data Center                      | Bitbucket Cloud                                                        |
| --------------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
| OAuth endpoints | Your instance (`{instance}/rest/oauth2/latest/...`) | Central (`bitbucket.org/site/oauth2/...`)                              |
| Authorization   | 3LO only (browser consent)                          | 3LO or 2LO                                                             |
| Scopes          | `REPO_READ`, `REPO_WRITE`                           | `account`, `repository`, `pullrequest`, `pipeline`, `webhook` (+write) |
| REST API        | v1.0 (`/rest/api/1.0`)                              | v2.0                                                                   |
| Webhook         | Manual, **one project-level** webhook               | Automatic, per repository                                              |

<Note>
  Bitbucket Data Center requires **DC 7.21 or newer** for the OAuth 2.0
  authorization-code provider (any 8.x LTS works).
</Note>

## Prerequisites

* A **Bitbucket Server or Data Center** instance reachable from your Overcut
  deployment over **HTTPS**
* **Administrator** access to that instance (to create the Application Link) and
  **project admin** on the target project (to create the webhook)
* 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. Authorize while signed in as a dedicated service
  account (for example `overcut-bot`), not your personal admin account. The service
  account must have write access to the target repositories.
</Warning>

## Connect

<Steps>
  <Step title="Create an OAuth 2.0 incoming Application Link">
    As a Bitbucket administrator, go to **Administration -> Application links ->
    Create link**, and select **External application** / **Incoming**.

    Set the **redirect (callback) URL** to your deployment's Overcut callback,
    exactly:

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

    This must match the `BITBUCKET_SERVER_REDIRECT_URI` server setting character
    for character, and must use **https**.

    In the **Application permissions** matrix, tick **Repositories: Write** (this
    auto-includes Read), which maps to the `REPO_READ` + `REPO_WRITE` scopes
    Overcut requests. Do **not** tick Admin / Projects / Account / System-admin -
    webhooks are added manually, so no admin scope is needed. Save, then copy the
    generated **Client ID** and **Client Secret**.
  </Step>

  <Step title="Connect in Overcut">
    In Overcut, open the git providers list and click the **Bitbucket Server /
    Data Center** tile. Enter:

    * **Instance URL**: your Bitbucket base URL (for example
      `https://bitbucket.your-company.com`)
    * the **Client ID** and **Client Secret** from the previous step

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

  <Step title="Register one project-level webhook in Bitbucket">
    Webhooks are configured in Bitbucket, separately from the Application Link.
    Open the connected org's **settings** page in Overcut (**View settings** on
    the provider page) to find the webhook **URL**
    (`https://<dispatcher>/webhooks/bitbucket/server/<orgId>`) and a revealable
    **secret**.

    In Bitbucket, go to **Project settings -> Webhooks -> Create webhook** (a
    project-level webhook is inherited by every repository in the project, so this
    is one paste per project, not per repo). Paste the **URL**, put the revealed
    **secret** in the webhook's **Secret** field (it signs the `X-Hub-Signature`
    HMAC the dispatcher verifies), and enable these events:

    * `pr:opened`, `pr:from_ref_updated`, `pr:modified`, `pr:merged`, `pr:declined`
    * `pr:reviewer:approved`, `pr:reviewer:unapproved`, `pr:reviewer:needs_work`
    * `pr:comment:added`

    Creating a project webhook requires **project admin** in Bitbucket (a
    one-time human step); the Overcut OAuth token itself stays write-only.
  </Step>
</Steps>

<Note>
  Bitbucket Data Center has no Pipelines product, so there are no CI/build-status
  webhook events on this path.
</Note>

## Deployment configuration

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

| Setting                                | Value                                                              | Notes                                                                                   |
| -------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `INTEGRATION_BITBUCKET_SERVER_ENABLED` | `true`                                                             | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. |
| `BITBUCKET_SERVER_REDIRECT_URI`        | `https://<your-overcut-domain>/bitbucket-server-auth-app/callback` | Must equal the Application Link redirect URL exactly.                                   |
| `DISPATCHER_BASE_URL`                  | `https://<dispatcher-or-app>/hooks`                                | External URL used to build the webhook URL shown in Overcut.                            |

## Troubleshooting

* **`redirect_uri` mismatch at Authorize**: the Application Link redirect URL and `BITBUCKET_SERVER_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`).
* **Token exchange returns 400 (PKCE)**: some instances require PKCE for the incoming link. Confirm the Application Link is configured to allow the authorization-code grant without mandatory PKCE, or contact Overcut support.
* **Authorize fails to reach Bitbucket**: the instance must be reachable from the Overcut deployment over HTTPS with a valid certificate. Confirm network access and TLS.
* **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.
* **Webhook events never fire**: confirm the webhook secret in Bitbucket matches the one shown in Overcut, the listed PR events are enabled, and `DISPATCHER_BASE_URL` is set to the external URL with `INTEGRATION_BITBUCKET_SERVER_ENABLED=true` on the dispatcher.

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