> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm/bitbucket-cloud.md).

# Bitbucket Cloud

Connect a Bitbucket Cloud workspace to Heeler with an Atlassian API token — fully supported, including PR guardrails.

Heeler connects to **Bitbucket Cloud** with an **Atlassian API token** scoped to Bitbucket. Bitbucket Cloud is **fully supported** — analysis, catalog, and [PR guardrails](/mrecEO40m5D6bt7Pq5pE/prevent/pr-guardrails.md) all run on it.

{% hint style="info" %}
On the **Add Code Organization** menu, this provider is listed as **Bitbucket**.
{% endhint %}

## Before you start

* An Atlassian account with access to the Bitbucket workspace.
* **Administrator** role in Heeler.
* Your Bitbucket **Username**, **Atlassian account email**, and **Workspace ID** (gathered below).

## Step 1 — Create a Bitbucket API token

1. Go to [id.atlassian.com → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and choose **Create API token with scopes**.
2. Give it a **Name** and set the expiration to the maximum (**1 year**).
3. Select **Bitbucket** as the product.
4. Add the permissions below, then **create** the token and **copy** it.

{% hint style="warning" %}
Only 10 permissions are shown at a time and these aren't in the first 10 — **search or page** through to select them all.
{% endhint %}

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-b11e790d51c4843c349e60b3dcf57d868af3b649%2Fcc-scm-bbcloud-01.png?alt=media" alt="The Atlassian API tokens page with Create API token with scopes."><figcaption><p>At id.atlassian.com, choose <strong>Create API token with scopes</strong>.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-3d760f8acb71469ea1f44936af42f1a8fec05bf1%2Fcc-scm-bbcloud-expiration.png?alt=media" alt="Setting the API token expiration date one year out."><figcaption><p>Set the expiration to the maximum (<strong>1 year</strong>).</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-d12224c845a0a6f2074f7821aa48e2fbc4e30f90%2Fcc-scm-bbcloud-03.png?alt=media" alt="Selecting Bitbucket as the product for the API token."><figcaption><p>Scope the token to <strong>Bitbucket</strong>.</p></figcaption></figure>

<table><thead><tr><th width="140">Access</th><th>Scopes</th></tr></thead><tbody><tr><td><strong>Read</strong></td><td><code>read:account</code>, <code>read:user:bitbucket</code>, <code>read:workspace:bitbucket</code>, <code>read:project:bitbucket</code>, <code>read:repository:bitbucket</code>, <code>read:pullrequest:bitbucket</code>, <code>read:pipeline:bitbucket</code>, <code>read:permission:bitbucket</code>, <code>read:webhook:bitbucket</code></td></tr><tr><td><strong>Write</strong></td><td><code>write:repository:bitbucket</code>, <code>write:pullrequest:bitbucket</code>, <code>write:pipeline:bitbucket</code>, <code>write:webhook:bitbucket</code></td></tr><tr><td><strong>Delete</strong></td><td><code>delete:webhook:bitbucket</code></td></tr></tbody></table>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-b212bee986325f8008c187a944b487b95f193477%2Fcc-scm-bbcloud-04.png?alt=media" alt="Selecting the Bitbucket read, write, and delete permissions for the API token."><figcaption><p>Select the read/write/delete permissions listed above.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-e9c43f74833be7311b2f9cf7eb9b9391dcf40e44%2Fcc-scm-bbcloud-05.png?alt=media" alt="Copying the generated Bitbucket API token."><figcaption><p>Copy the generated token — it's shown only once.</p></figcaption></figure>

## Step 2 — Gather your Bitbucket details

Heeler uses your Atlassian identity and workspace for API and webhook operations. Collect:

<table><thead><tr><th width="220">Value</th><th>Where to find it</th></tr></thead><tbody><tr><td><strong>Username</strong></td><td><strong>Settings → Personal Bitbucket settings → Bitbucket profile settings</strong>.</td></tr><tr><td><strong>Email</strong></td><td>Your <strong>Atlassian account email</strong> (Settings → Email aliases).</td></tr><tr><td><strong>Workspace ID</strong></td><td><strong>Settings → Workspace settings</strong> — copy the <strong>Workspace ID</strong>.</td></tr></tbody></table>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2F3d1pmxPC7Uiku7nxmCIu%2F1%20--%20Personal%20Bitbucket%20settings.png?alt=media&amp;token=192416ec-2c1b-4514-bffd-c8d23b02b500" alt="Opening Personal Bitbucket settings from the Bitbucket account settings menu."><figcaption><p>Under <strong>Account settings</strong>, open <strong>Personal Bitbucket settings</strong>.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-2fb1ee3e24f4b4c2d60fb37e40b0c00264c5a7a0%2Fcc-scm-bbcloud-07.png?alt=media" alt="Bitbucket profile settings showing the username."><figcaption><p>Copy your <strong>Username</strong> from Bitbucket profile settings.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2FWpXmosTGgXZQqU16WbcV%2F3--%20Bitbucket%20email.png?alt=media&amp;token=56aae055-b228-49a9-b4bc-90a7897945d7" alt="The Email aliases page showing the Atlassian account email address."><figcaption><p>Use your <strong>Atlassian account email</strong> from <strong>Email aliases</strong> as your Bitbucket email.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2FOfTRSIUMro0Y5SnxFuLB%2F4%20--%20Workspace%20Bitbucket%20settings.png?alt=media&amp;token=86f0378e-4f99-4c32-80b6-959328229ce2" alt="Opening Workspace settings from the Bitbucket account settings navigation."><figcaption><p>Open <strong>Workspace settings</strong> to find the Workspace ID.</p></figcaption></figure>

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-2d231558db180035e65882b4a3c305a77bd6d5e6%2Fcc-scm-bbcloud-10.png?alt=media" alt="Bitbucket workspace settings showing the Workspace ID."><figcaption><p>Copy the <strong>Workspace ID</strong> from Workspace settings.</p></figcaption></figure>

## Step 3 — Add Bitbucket Cloud to Heeler

{% stepper %}
{% step %}

### Open Code Organizations

Click the **Settings** (gear) icon → **Connections → Code Organizations → Add Code Organization → Bitbucket**.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-1989138f9f2c354d19da7b24c1e6dfa1c983eacc%2Fcc-scm-bbcloud-add-org.png?alt=media" alt="The Code Organizations settings page with the Add Code Organization button."><figcaption><p>On <strong>Code Organizations</strong>, click <strong>Add Code Organization</strong>.</p></figcaption></figure>
{% endstep %}

{% step %}

### Fill in the Credentials tab

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-917972a36ae37b058b1b4ed86da014bbe0a90b90%2Fcc-gs-scm-bbcloud-form.png?alt=media" alt="The Add Bitbucket Organization wizard, Credentials step, with Connection Name, Username, Email, API Token, and Workspace ID fields, ahead of Webhook and Summary steps."><figcaption><p>The Bitbucket Cloud connection wizard: Credentials → Webhook → Summary.</p></figcaption></figure>

* **Connection Name** — a display name.
* **Username** — from Step 2.
* **Email** — your Atlassian account email.
* **API Token** — from Step 1.
* **Workspace ID** — from Step 2 (required for webhook creation).

Click **Save & Continue**.
{% endstep %}

{% step %}

### Confirm the webhook and summary

On the **Webhook** tab, Heeler creates a webhook to receive updates from your workspace — click **Next**.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-73d600f6d16f72191cd7450592221a096e1c212d%2Fcc-scm-bbcloud-webhook.png?alt=media" alt="The Webhook step of the Bitbucket connection wizard showing the webhook Heeler will create."><figcaption><p>Heeler creates a webhook to receive updates from your workspace. Click <strong>Next</strong>.</p></figcaption></figure>

Review the **Summary** and click **Done**.

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-41aea4bc958dfd18399ed92d7102355f830863ef%2Fcc-scm-bbcloud-summary.png?alt=media" alt="The Summary step of the Bitbucket connection wizard."><figcaption><p>Review the <strong>Summary</strong> and click <strong>Done</strong>.</p></figcaption></figure>
{% endstep %}

{% step %}

### Verify

Confirm the connection shows **Healthy**, and that repositories appear in the [Catalog](/mrecEO40m5D6bt7Pq5pE/catalog/repositories.md).

<figure><img src="https://414480750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXP3dp2kecwKA2KvYkntz%2Fuploads%2Fgit-blob-fbe0298fea67cfc37aaed33d5232c8f5ba6400cb%2Fcc-scm-bbdc-healthy.png?alt=media" alt="The Bitbucket Cloud connection showing a Healthy status."><figcaption><p>A successful connection shows <strong>Healthy</strong>.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Troubleshooting

<table><thead><tr><th width="280">Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>Connection <strong>Unhealthy</strong></td><td>Confirm the API token is scoped to Bitbucket with all the listed permissions and hasn't expired, and that Username / Email / Workspace ID are correct.</td></tr><tr><td>Webhook didn't create</td><td>Confirm the <strong>Workspace ID</strong> is correct and the token includes <code>write:webhook:bitbucket</code>.</td></tr></tbody></table>

## Related

* [Bitbucket Data Center](/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm/bitbucket-data-center.md) — the self-hosted variant.
* [Connect Your Code](/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm.md) — the common flow and network requirements.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm/bitbucket-cloud.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.