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

# Bitbucket Data Center

> Connect your self-hosted Bitbucket Data Center (Server) repositories to Gitar

<Note>Bitbucket Data Center support is currently in **beta**. For access or to leave feedback, please email us at: [developers@gitar.ai](mailto:developers@gitar.ai)</Note>

## Overview

Gitar connects to self-hosted Bitbucket Data Center instances via an access token associated with a dedicated service account. Gitar uses this token to read pull requests, post review comments, and register webhooks that deliver events to Gitar in real time.

Bitbucket Data Center is different from Bitbucket Cloud: there is no Atlassian Forge app for self-hosted instances, so the connection is token-based instead, similar to how Gitar connects to self-managed GitLab or Azure DevOps.

## Prerequisites

* A Bitbucket Data Center instance (version 7.x or later) reachable from Gitar's network — an on-premises VPN, IP allowlist, or same-VPC/same-cloud connection. Fully firewalled/air-gapped instances are not yet supported; contact us if this applies to you.
* Permission to create a service account (user) on your Bitbucket Data Center instance
* Project Administrator permission on the projects you want to connect

## Setup Instructions

<Steps>
  <Step title="Create a dedicated service account">
    Create a new user on your Bitbucket Data Center instance to act as the Gitar service account (e.g. `gitar-bot`).

    **A dedicated account with a valid email address is required, not optional.** Gitar identifies its own comments by the account that owns the token and ignores them to avoid processing its own output. The account also needs a valid email address — Bitbucket Data Center rejects pull request merges from users with no email set, which blocks Gitar's auto-merge feature.
  </Step>

  <Step title="Grant project access">
    The service account needs at least **Write** permission on each project you want Gitar to access, so it can read pull requests and post comments/reviews. **Project Administrator** permission is additionally required on projects where you want Gitar to auto-provision webhooks during setup.

    For each project: go to **Project settings → Permissions** and add the service account with the appropriate role.
  </Step>

  <Step title="Generate an access token">
    Sign in as the Gitar service account and create a token. You can choose either:

    * **A personal HTTP access token** (scoped to everything the account can access) — go to your **profile avatar → Manage account → Personal access tokens → Create token**.
    * **A repository or project access token** (scoped to a single repo/project) — go to the repository or project's **Settings → Access tokens → Create token**. Use this if you want to limit Gitar's access to specific repositories rather than everything the service account can see.

    Either way, grant **Read** and **Write** permission at the repository level (and **Project admin** if you want Gitar to auto-provision webhooks).

    <Callout type="warn" title="Token expiry">
      Set an expiration date and note it — Gitar will stop working when the token expires, and will surface this in the dashboard as an unhealthy integration. To rotate, generate a new token with the same scopes and update it under **Settings → Integrations → Bitbucket Data Center → Update token**.
    </Callout>
  </Step>

  <Step title="Connect in Gitar">
    1. In the Gitar dashboard, go to **Settings → Integrations**
    2. Click **Connect** next to Bitbucket Data Center
    3. Enter your instance's base URL (e.g. `https://bitbucket.yourcompany.com`)
    4. Select the token type (personal vs. repository/project) and paste the token
    5. Select the projects/repositories you want Gitar to access
    6. Click **Connect**

    Gitar validates the token (reachability, permissions, and — if you plan to use auto-merge — that the account has a valid email) and registers webhooks on the selected repositories automatically. If the service account lacks Project Administrator permission, Gitar shows the webhook URL and secret for manual setup instead.
  </Step>
</Steps>

## Network reachability

Gitar's data plane must be able to reach your Bitbucket Data Center instance's REST API over HTTPS, and your instance must be able to send webhook requests to Gitar. If your instance is behind a firewall with no route to the public internet, reach out — outbound-only tunnel connectivity for fully firewalled instances is on our roadmap but not yet available.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Validation fails with a permissions error">
    The service account (or the token's scope, if using a repository/project token) doesn't have sufficient permission on the project or repository. Grant at least Read & Write, and Project Administrator if you want automatic webhook setup.
  </Accordion>

  <Accordion title="Auto-merge doesn't work">
    The service account has no email address set, or an invalid one. Bitbucket Data Center rejects merges from accounts without a valid email — set one on the service account and reconnect.
  </Accordion>

  <Accordion title="Gitar stops working after some time">
    The access token has likely expired. Go to **Settings → Integrations → Bitbucket Data Center**, click **Update token**, and paste a newly generated token.
  </Accordion>

  <Accordion title="Webhooks aren't arriving">
    Confirm your instance can reach Gitar's webhook endpoint over the public internet (or your configured private connection), and that no corporate proxy is stripping the `X-Hub-Signature` header. If the service account lacks Project Administrator permission, webhooks must be registered manually — check **Settings → Integrations → Bitbucket Data Center** for the webhook URL and secret to configure yourself.
  </Accordion>

  <Accordion title="I changed my instance's base URL">
    Changing the base URL (e.g. moving to a new domain) breaks the integration because Gitar uses it to route API calls and validate webhook signatures. Reconnect from **Settings → Integrations → Bitbucket Data Center → Disconnect**, then reconnect with the new URL.
  </Accordion>
</AccordionGroup>