Skip to main content
The Bitbucket Cloud integration enables GitOps workflows for Ankra clusters using OAuth-authenticated workspace access.

​
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

1

Open the Credentials page

In Ankra, navigate to Organisation → Credentials → Add credential.
2

Pick Bitbucket Cloud

Select Bitbucket Cloud from the source-control providers and click Continue to Bitbucket.
3

Authorise the Ankra OAuth consumer

Bitbucket will redirect you to the consent screen. Review the requested scopes and click Grant access.
4

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.

​
Connecting a repository to a cluster

1

Open the cluster's GitOps settings

Navigate to the cluster, click Settings → GitOps.
2

Pick Bitbucket Cloud

Use the provider switcher to select Bitbucket Cloud, then choose the credential and the repository to attach.
3

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.

​
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.