--- title: "Bitbucket Cloud" description: "Use Bitbucket Cloud: pull requests, issues, build statuses, repository contents and webhooks." canonical_url: "https://docs-8831a2g1f-poetry.vercel.app/providers/bitbucket" --- # Bitbucket Cloud > Use Bitbucket Cloud: pull requests, issues, build statuses, repository contents and webhooks. The Bitbucket provider covers Bitbucket Cloud (bitbucket.org). It reads and writes pull requests, issues and commit comments. It also covers build statuses, repository contents and repository and workspace webhooks. Bitbucket has no notifications, labels, releases or reactions, so those capabilities are `false`.

Detail	Value
Import	`forges/bitbucket`
Factories	`bitbucket()` , `bitbucketLite()`
Auth	`token` , `basic` , `anonymous`

## Authentication The provider accepts an access token or Basic credentials: - An access token is an OAuth token, or a repository, project or workspace access token. - Basic credentials are a username and app password, or an Atlassian account email and API token. ```ts import { bitbucket } from 'forges/bitbucket' const forge = bitbucket({ auth: { type: 'token', token: process.env.BITBUCKET_TOKEN! }, }).create() const basic = bitbucket({ auth: { type: 'basic', username: process.env.BITBUCKET_USERNAME!, password: process.env.BITBUCKET_APP_PASSWORD!, }, }).create() ``` Without `auth`, the provider makes anonymous public reads. ## Instance The instance is `bitbucket.org`, and the API base URL defaults to `https://api.bitbucket.org/2.0`. A repository's `owner` is the workspace slug, and `name` is the repository slug. `repoKey()` uses the repository's UUID, so the key stays the same when the repository is renamed. ## Issues and repository listing Bitbucket Cloud has retired its issues API and the unscoped repositories listing. The provider implements both and reports them as `'experimental'`. `repos.list()` lists the repositories that the account is a member of. ## Merging If you don't pass `method`, `merge()` reads the merge strategies allowed on the destination branch. When exactly one strategy is allowed, it uses that strategy. When several are allowed, it throws `MergeMethodRequiredError`. Pass `sha` to check the head of the pull request before merging. If the head doesn't match, the call throws `MergeConflictError`. `whenChecksPass` is unavailable. Bitbucket can't reopen a declined pull request, so `reopen()` rejects for pull requests. ## Participants as reviews `threads.reviews()` returns one review for each participant who has voted, with the ID `participant:`. `createReview()` accepts the `approve` and `request_changes` events. A body or inline comments reject with `UnsupportedOperationError`. ## Markdown Bitbucket doesn't render HTML elements such as `

`. `forge.normaliseMarkdown(body)` turns each `

` into bold text and removes the `

` tags. ## Accounts Bitbucket reads accounts by UUID or Atlassian account ID, and nicknames aren't unique. For this reason, `users.get(login)` is unavailable. ## Webhooks Set `webhookSecret` to the secret configured on the hook. Bitbucket signs a delivery only when the hook has a secret, so deliveries from a hook without a secret don't verify. ```ts const forge = bitbucket({ webhookSecret: process.env.BITBUCKET_WEBHOOK_SECRET, }).create() const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` Bitbucket sends these headers with each delivery:

Header	Content
`X-Hub-Signature`	`sha256=` followed by the hex HMAC-SHA256 of the body
`X-Event-Key`	The event name
`X-Request-UUID`	The delivery ID

Bitbucket has no delivery log, so `webhooks.deliveries()` and `webhooks.redeliver()` are unavailable. ## Recording fixtures ```sh BITBUCKET_TOKEN=... FIXTURE_BITBUCKET_REPO=workspace/repo \ FIXTURE_BITBUCKET_PULL=1 pnpm record-fixtures bitbucket ``` To use Basic credentials, set `BITBUCKET_USERNAME` and `BITBUCKET_APP_PASSWORD` in place of `BITBUCKET_TOKEN`. To add an issue, set `FIXTURE_BITBUCKET_ISSUE`. ## Capabilities Generated by `pnpm capability-matrix`; do not edit by hand.

Capability	Support
`experimental`	❌
`sources.poll`	❌
`sources.webhook`	✅
`sources.subscribe`	❌
`repos.get`	✅
`users.get`	❌
`repos.list`	experimental
`repos.labels`	❌
`repos.createLabel`	❌
`repos.milestones`	❌
`repos.collaborators`	❌
`repos.permissionFor`	❌
`repos.addCollaborator`	❌
`repos.assignableUsers`	❌
`repos.reviewerCandidates`	❌
`threads.get`	issue (experimental), PR, commit (experimental)
`threads.list`	issue (experimental), PR
`threads.getMany`	✅
`comments.list`	issue (experimental), PR, commit (experimental)
`comments.edit`	issue (experimental), PR (experimental), commit (experimental)
`comments.delete`	issue (experimental), PR (experimental), commit (experimental)
`reactions.list`	❌
`notifications.list`	❌
`notifications.markRead`	❌
`notifications.markDone`	❌
`notifications.unsubscribe`	❌
`notifications.markAllRead`	❌
`notifications.markAllDone`	❌
`notifications.unreadCount`	❌
`writes.comment`	issue (experimental), PR, commit (experimental)
`writes.upsertComment`	issue (emulated), PR (emulated), commit (emulated)
`writes.close`	issue (experimental), PR
`writes.reopen`	issue (experimental)
`writes.create`	issue (experimental), PR (experimental)
`writes.update`	issue (experimental), PR (experimental)
`writes.setLabels`	❌
`writes.addLabels`	❌
`writes.removeLabels`	❌
`writes.setMilestone`	❌
`writes.react`	❌
`writes.setAssignees`	issue (experimental)
`writes.requestReview`	PR (experimental)
`writes.merge`	✅
`writes.approveAndMerge`	✅
`writes.transfer`	❌
`writes.markDuplicate`	❌
`subscriptions.get`	issue (experimental)
`subscriptions.set`	issue (experimental)
`installations`	❌
`checks.thread`	PR
`checks.list`	✅
`checks.report`	experimental
`checks.rerun`	❌
`ci.runs`	❌
`ci.run`	❌
`ci.jobs`	❌
`ci.log`	❌
`contents.file`	✅
`contents.tree`	✅
`contents.branches`	✅
`contents.tags`	✅
`contents.resolveRef`	✅
`contents.commits`	✅
`contents.commit`	✅
`contents.compare`	✅
`contents.threadFiles`	✅
`contents.threadCommits`	✅
`reviews.list`	emulated
`reviews.create`	emulated
`reviews.submit`	❌
`reviews.approve`	emulated
`reviews.resolveThread`	❌
`releases.list`	❌
`releases.get`	❌
`releases.latest`	❌
`releases.getByTag`	❌
`releases.downloadAsset`	❌
`webhooks.list`	experimental
`webhooks.create`	experimental
`webhooks.update`	experimental
`webhooks.delete`	experimental
`webhooks.rotateSecret`	experimental
`webhooks.deliveries`	❌
`webhooks.redeliver`	❌
`search.threads`	experimental
`search.repos`	experimental
`search.commits`	❌
`securityAlerts`	❌
`eventKinds`	native
`auth`	`token` , `basic` , `anonymous`
`limits`	unknown

## Sitemap See the full [sitemap](https://docs-8831a2g1f-poetry.vercel.app/sitemap.md) for all pages.