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

# Bitbucket Cloud Integration

> Connect Bitbucket Cloud workspaces for GitOps workflows and configuration management

<Note>
  The Bitbucket Cloud integration enables GitOps workflows for Ankra clusters using OAuth-authenticated workspace access.
</Note>

## Overview

Connecting Bitbucket Cloud to Ankra enables:

* **Configuration Storage:** Store Helm values and manifests in your workspace repositories
* **Version Control:** Track all infrastructure changes with Git history
* **GitOps Workflows:** Sync changes between Ankra and your repository through `repo:push` webhooks
* **Audit Trail:** Full history of who changed what and when
* **Collaboration:** Use pull requests and code review for infrastructure changes

***

## Prerequisites

You need:

* A Bitbucket Cloud workspace you own or are an admin of.
* Permission to authorise OAuth consumers for that workspace.

Ankra requests the following OAuth scopes:

* `account` - read account metadata for the connected user.
* `repository` - read access to repositories visible to your account.
* `repository:write` - push commits with stack configuration.
* `repository:admin` - register and rotate the per-credential webhook.
* `webhook` - receive `repo:push` events for GitOps sync.

***

## Connecting Bitbucket Cloud

<Steps>
  <Step title="Open the Credentials page">
    In Ankra, navigate to **Organisation → Credentials → Add credential**.
  </Step>

  <Step title="Pick Bitbucket Cloud">
    Select **Bitbucket Cloud** from the source-control providers and click **Continue to Bitbucket**.
  </Step>

  <Step title="Authorise the Ankra OAuth consumer">
    Bitbucket will redirect you to the consent screen. Review the requested scopes and click **Grant access**.
  </Step>

  <Step title="Verify the credential appears">
    You will land back in Ankra with the new Bitbucket Cloud credential listed. The repository scraper job runs immediately and the credential's repository list populates within a minute.
  </Step>
</Steps>

***

## Connecting a repository to a cluster

<Steps>
  <Step title="Open the cluster's GitOps settings">
    Navigate to the cluster, click **Settings → GitOps**.
  </Step>

  <Step title="Pick Bitbucket Cloud">
    Use the provider switcher to select **Bitbucket Cloud**, then choose the credential and the repository to attach.
  </Step>

  <Step title="Confirm">
    Ankra writes a `clusters/{cluster-name}-{cluster-short-id}/` folder to the repository on the next sync. A `repo:push` webhook is registered automatically - there is no manual webhook setup.
  </Step>
</Steps>

***

## Webhook delivery

* Per-credential URL: `{platform-base-url}/webhooks/bitbucket-cloud/{credential-id}`.
* Event filter: `repo:push` only.
* Signature: `X-Hub-Signature: sha256=<hmac>` validated on every request.

If a webhook delivery fails, Bitbucket retries with exponential backoff. Investigate by checking the webhook details on the credential page in Ankra.

***

## Limitations

* Only HTTPS authentication is supported. SSH keys are not used for Bitbucket Cloud.
* Atomic multi-file commits are written using the `POST /2.0/repositories/{ws}/{repo}/src` endpoint with up to 5 retries on conflict.

***

## Troubleshooting

* **OAuth callback errors** appear as `?bitbucket_error=...` on the credentials page after the redirect. The error code comes from Bitbucket's OAuth response (e.g. `access_denied`).
* **Token refresh failures** show the credential as `Down`. Reconnect the credential to mint a fresh refresh token.
* **No repositories visible** typically means the OAuth user lacks `repository` scope on the workspace. Re-run the OAuth flow.