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

# Bitbucket

> Create a Bitbucket OAuth consumer to enable Bitbucket sign-in for your on-prem Garth Assist deployment.

<Info>
  This page covers **on-prem (self-hosted)** setup. You create your own Bitbucket
  OAuth consumer so authentication runs against your workspace. For the hosted
  SaaS integration, see [Setup → Bitbucket](https://app.heygarth.ai/settings/integrations).
</Info>

<Warning>
  You need **admin access** to the Bitbucket workspace to create an OAuth consumer.
</Warning>

## Create the Bitbucket OAuth consumer

<Steps>
  <Step title="Open OAuth consumers">
    In Bitbucket, go to **Workspace settings → OAuth consumers** and click
    **Add consumer**.
  </Step>

  <Step title="Fill in the details">
    | Field            | Value                                                          |
    | ---------------- | -------------------------------------------------------------- |
    | **Name**         | `Garth Assist`                                                 |
    | **Callback URL** | `https://<dns-host>/api/garth-assist/oauth/bitbucket/callback` |

    <Tip>
      Replace `<dns-host>` with the DNS host of your on-prem Garth deployment —
      for example `https://app.heygarth.ai/api/garth-assist/oauth/bitbucket/callback`.
    </Tip>
  </Step>

  <Step title="Select permissions">
    Grant the following permissions:

    | Permission               | Access             |
    | ------------------------ | ------------------ |
    | **Account**              | Read               |
    | **Workspace membership** | Read, Write        |
    | **Projects**             | Read, Write        |
    | **Repositories**         | Read, Write, Admin |
    | **Pull requests**        | Read, Write        |
    | **Issues**               | Read               |
    | **Pipelines**            | Read               |
    | **Runners**              | Read               |
  </Step>

  <Step title="Save the consumer">
    Click **Save**. Expand the consumer to view its **Key** and **Secret**.

    <Warning>
      Store the **Secret** securely — treat it like a password.
    </Warning>
  </Step>
</Steps>

## Environment variables

Record the following values for your on-prem deployment:

| Environment variable      | Value                   |
| ------------------------- | ----------------------- |
| `BITBUCKET_CLIENT_ID`     | The consumer **Key**    |
| `BITBUCKET_CLIENT_SECRET` | The consumer **Secret** |