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

> Connect your Bitbucket repositories to Gitar

export const ThemeImage = ({src, alt}) => {
  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;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

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

## Install the Gitar Bitbucket app

Bitbucket repositories are connected to Gitar by installing the Gitar Bitbucket app, built on Atlassian's Forge platform. The app handles authentication, permissions, and webhook delivery, so there are no tokens or secrets to manage.

<ThemeImage src="/assets/images/conn-bitbucket-dark.png" alt="Connect Bitbucket" />

## Prerequisites

* A Gitar organization (not a personal account) with the **Admin** role
* A Bitbucket account with access to the workspace you want to connect
* Permission to install a Forge app on that Bitbucket workspace (workspace admin)

## Setup Instructions

<Steps>
  <Step title="Open the connect dialog">
    In the Gitar dashboard, go to **Settings → Repositories** and click **Connect Bitbucket** (or use the "Connect your repositories" step during onboarding).
  </Step>

  <Step title="Connect your Bitbucket account">
    The first time you connect Bitbucket, Gitar asks you to authorize with your Bitbucket account via OAuth. This is a one-time step that lets Gitar list the workspaces you have access to.

    <ThemeImage src="/assets/images/bitbucket-connect-account-dark.png" alt="Connect your Bitbucket account" />
  </Step>

  <Step title="Select the workspace">
    Choose the Bitbucket workspace you want to connect to this Gitar organization. Workspaces already connected to your organization are marked as such, and workspaces connected to a different Gitar organization show as "Connected to another organization" — a workspace can only be linked to one Gitar org at a time.

    <ThemeImage src="/assets/images/bitbucket-select-workspace-dark.png" alt="Select the Bitbucket workspace" />
  </Step>

  <Step title="Install the Forge app">
    Gitar opens a new browser tab to Atlassian, where you install the Gitar Forge app.

    <Callout type="warn" title="Install on the same workspace">
      Atlassian will ask you to pick a workspace to install on. **You must pick the same workspace you just selected in Gitar.** If you install on a different workspace, Gitar has no way to match the install to your selection — the connection silently fails and the workspace you picked in Gitar never connects.
    </Callout>

    <ThemeImage src="/assets/images/bitbucket-forge-install.png" alt="Install the Gitar Forge app on Atlassian" />
  </Step>

  <Step title="Return to Gitar and wait">
    <Callout type="info" title="No automatic redirect">
      Atlassian does not redirect you back to Gitar after installation. Switch back to the Gitar browser tab yourself.
    </Callout>

    While it waits, the dialog shows a "Waiting for installation…" state. Gitar detects the completed install within a few seconds up to about a minute. The connect dialog closes automatically once detected, and all repositories in the workspace are discovered and ready for review — no per-repository picker is needed.

    <ThemeImage src="/assets/images/bitbucket-waiting-dark.png" alt="Waiting for the Bitbucket installation to complete" />
  </Step>
</Steps>

## Repository access

Once connected, Gitar automatically discovers every repository in the workspace. Head to **Settings → Repositories** to see the full list and toggle individual repositories on or off.

<ThemeImage src="/assets/images/bitbucket-repositories-dark.png" alt="Bitbucket repositories" />

## Permissions

The Gitar Forge app requests the following capabilities:

* **Read workspace** — list workspaces and repositories so Gitar can discover what's available to connect
* **Read and write repository** — read code and diffs, and push changes such as fix commits
* **Read and write pull requests** — read pull request metadata and diffs, and post review comments
* Receive pull request and repository events in real time, so Gitar can react to new PRs and pushes without polling

Gitar **does not store your code**. Code is checked out, processed, and discarded.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Installation not detected' / the dialog timed out">
    This usually means the install either was not completed on Atlassian, or was completed on a different workspace than the one selected in Gitar. Make sure you install the Forge app on the **same workspace** you selected in the Gitar dialog, then switch back to the Gitar tab. If the dialog already timed out, use **Reopen install link** to try again.
  </Accordion>

  <Accordion title="A workspace shows 'Connected to another organization'">
    A Bitbucket workspace can only be linked to one Gitar organization at a time. If you need to connect it here, disconnect it from the other organization first.
  </Accordion>

  <Accordion title="I don't see my workspace in the list">
    Your Bitbucket account needs access to the workspace. Confirm you have access in Bitbucket, then reconnect your account from the Gitar dialog.
  </Accordion>

  <Accordion title="Gitar isn't reviewing my pull requests">
    Confirm the Gitar Forge app is installed on the workspace and that the specific repository is enabled (toggled on) in the **Settings → Repositories** card.
  </Accordion>
</AccordionGroup>