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

export const ThemeImage = ({src, alt, width}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  const style = width ? {
    maxWidth: width,
    marginInline: "auto"
  } : undefined;
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} style={style} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} style={style} />
    </span>;
};

<Note>
  For what differs between this platform and the others, see [Platform Support](/connecting-code/platform-support).
</Note>

## Overview

Two paths connect a self-hosted instance, and you only need one.

**The Gitar app** is a plugin you upload to your instance. It forwards pull request and build events to Gitar from inside Bitbucket, sets up its own credentials where Bitbucket allows it, and registers Gitar's commit-signing key on the bot account so pushed commits show as Verified. This is the recommended path.

**A service-account token** is the alternative: you create a user, generate an access token, and paste it into Gitar. Gitar then registers a webhook on each repository you connect. Use this if you would rather not install a plugin, or if your change-management process makes app installs slow.

Bitbucket Data Center is different from Bitbucket Cloud, where Gitar installs through the Atlassian Marketplace. Forge is Cloud-only, so a self-hosted instance has no Marketplace install.

## Prerequisites

* A Bitbucket Data Center or Server 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 or air-gapped instances are not supported, so contact us if that applies to you.
* Bitbucket administrator access, to install the app or to create a service account.

## Option A: Install the Gitar app

<Steps>
  <Step title="Allow app uploads">
    Bitbucket 10 disables uploading apps through the admin UI by default, and checks app signatures. The Gitar app is a private build, so both need turning off before the upload will work. Add these to your instance's JVM arguments and restart:

    ```text theme={null}
    -Dupm.plugin.upload.enabled=true
    -Datlassian.upm.signature.check.disabled=true
    ```

    On Bitbucket Server 7.x and Data Center 8.x-9.x, neither flag is needed.
  </Step>

  <Step title="Upload the app">
    In Bitbucket, go to **Administration → Manage apps → Upload app**.

    Gitar's connect dialog (**Settings → Configuration → Bitbucket → Server**) shows a copyable URL for each build. Paste it into the **Upload from URL** field. Two builds exist, and you need the one matching your version:

    * **Bitbucket Data Center 10.x** - the Jakarta build
    * **Bitbucket Server 7.x / Data Center 8.x-9.x** - the standard build

    If your instance has no outbound internet access, download the JAR from the same dialog and pick it from disk instead.
  </Step>

  <Step title="Connect it with a code">
    <ThemeImage src="/assets/images/bitbucket-data-center-connect-light.png" alt="Bitbucket Server app connection flow with installation URLs and the connect-code control" />

    The app runs inside your instance and cannot tell which Gitar organization installed it, so a one-time code is the whole handoff.

    1. In Gitar, go to **Settings → Configuration → Bitbucket → Server** and click **Generate a connect code**
    2. In Bitbucket, go to **Administration → Gitar**, paste the code, and click **Connect**

    The code is single use and expires after 30 minutes. Generating a new one invalidates the old one, so the button is safe to click again if you lose the code.

    The app reports its own base URL and server ID, so there is nothing else to type. It also mints the bot account's access token where Bitbucket permits it - version 10.x refuses to create a token on behalf of another user, and there the app's own screen asks you to paste one instead.
  </Step>
</Steps>

## Option B: Connect with a service-account token

<Steps>
  <Step title="Create a dedicated service account">
    Create a new user on your instance to act as the Gitar service account, for example `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 and reviews. **Project Administrator** permission is also required on projects where you want Gitar to register webhooks for you.

    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 or 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 register webhooks for you.

    <Callout type="warn" title="Token expiry">
      Set an expiration date and note it. Gitar stops working when the token expires and surfaces this in the dashboard as an unhealthy integration. To rotate, generate a new token with the same scopes, then **Disconnect** and reconnect the Server connection under **Settings → Configuration → Bitbucket → Server** with the new token.
    </Callout>
  </Step>

  <Step title="Connect in Gitar">
    1. In the Gitar dashboard, go to **Settings → Configuration**
    2. Click **Connect** next to Bitbucket, then open the **Server** tab
    3. Enter your instance's base URL, for example `https://bitbucket.yourcompany.com`
    4. Select the token type (personal, or repository/project) and paste the token
    5. Select the projects 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. It then registers webhooks on the selected repositories automatically.

    If the service account lacks Project Administrator permission, Gitar reports which repositories failed webhook setup. Grant the permission and reconnect to retry.
  </Step>
</Steps>

## Adding Repositories Later

Repositories created after you connect are not picked up automatically. Click **Refresh** on **Settings → Configuration → Repositories** to re-scan every connected instance.

On a service-account connection this also registers a webhook on each new repository, which is what makes Gitar see its pull requests at all - so run it after creating a repository, not only when the list looks stale. Repositories deleted since the last scan are dropped from the list.

## Network Reachability

Gitar's data plane must be able to reach your instance's REST API over HTTPS, and your instance must be able to send webhook requests to Gitar. If your instance enforces an IP allowlist, add Gitar's public IP addresses to it. See [Network Access](/connecting-code/network-access) for the addresses.

Gitar has no outbound-only tunnel, so an instance with no route to the public internet cannot connect. Contact us if that is your setup.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The app upload button is missing or the upload is rejected">
    On Bitbucket 10, app uploads are disabled by default and app signatures are checked. Add `-Dupm.plugin.upload.enabled=true` and `-Datlassian.upm.signature.check.disabled=true` to the JVM arguments and restart. If the upload is rejected as an incompatible plugin, you picked the wrong build - 10.x needs the Jakarta one.
  </Accordion>

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

  <Accordion title="Gitar doesn't see a repository I created">
    Click **Refresh** on **Settings → Configuration → Repositories**. On a service-account connection, a new repository has no webhook until this runs, so it delivers no events at all.
  </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. Generate a new token with the same scopes, then **Disconnect** and reconnect the Server connection under **Settings → Configuration → Bitbucket → Server** with the new token.
  </Accordion>

  <Accordion title="Commits from Gitar show as unverified">
    Gitar's signing key isn't registered on the bot account. The app registers it at connect time, so reconnecting through the app fixes this. On a service-account connection there is nothing to register the key, and commits stay unverified - this is cosmetic and doesn't affect anything else.
  </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, Gitar reports which repositories failed webhook setup. Grant the permission and reconnect to retry.
  </Accordion>

  <Accordion title="I changed my instance's base URL">
    Changing the base URL, for example moving to a new domain, breaks the integration because Gitar uses it to route API calls and validate webhook signatures. Disconnect and reconnect with the new URL. If you connected through the app, the app reports the new URL itself and Gitar moves the existing connection over.
  </Accordion>
</AccordionGroup>

## Draft pull requests

The **Skip draft PRs** setting works on Bitbucket Data Center 10.x and later, which reports draft state on its pull request events. Earlier versions do not, so Gitar reviews drafts there regardless of the setting.


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