--- title: "Bitbucket Cloud" description: "Use Bitbucket Cloud: pull requests, build statuses, repository contents and webhooks." canonical_url: "https://forges.link/providers/bitbucket" --- # Bitbucket Cloud > Use Bitbucket Cloud: pull requests, build statuses, repository contents and webhooks. The Bitbucket provider works with Bitbucket Cloud (bitbucket.org). It can read and write pull requests and commit comments, and it also covers build statuses, repository contents and the webhooks of repositories and workspaces. 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 the email of an Atlassian account together with an API token. Bitbucket Cloud has retired app passwords, so they no longer work: ```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_EMAIL!, password: process.env.BITBUCKET_API_TOKEN!, }, }).create() ``` If you leave out `auth`, the provider makes anonymous reads of public data. ## Instance The instance is always `bitbucket.org`, and the base URL of the API defaults to `https://api.bitbucket.org/2.0`. In a repository ref, `owner` is the slug of the workspace and `name` is the slug of the repository. `repoKey()` is built on the UUID of the repository, so the key stays the same when the repository is renamed. ## Issues and repository listing Bitbucket Cloud has [no issue tracker](https://developer.atlassian.com/cloud/bitbucket/changelog/#CHANGE-3401), so every issue capability is `false`. As a result, `threads.list()` without a `kind` lists pull requests. Bitbucket Cloud also lists repositories one workspace at a time. To give you a single list, `repos.list()` and `search.repos()` without an `owner` read the workspaces that the account belongs to, and then the repositories that it is a member of in each of them. `repos.byOwner()` lists the repositories of one workspace, which also covers the personal workspace of a user. Bitbucket has no internal repositories, so `visibility: 'internal'` returns an empty page with a `filter_unsupported` warning. Bitbucket doesn't record pushes, so `sort: 'pushed'` sorts by update time and adds a `sort_unsupported` warning. ## Merging If you call `merge()` without a `method`, the provider reads the merge strategies that the destination branch allows. When exactly one strategy is allowed, it uses that one. When several are allowed, it throws `MergeMethodRequiredError`. To make sure that you merge what you reviewed, pass `sha`. The provider then checks the head of the pull request before it merges, and the call throws `MergeConflictError` if the head doesn't match. The `whenChecksPass` option isn't available. `merge()` resolves with the merge commit from the response. When the merge takes longer than Bitbucket's timeout, Bitbucket finishes it in the background, and `merge()` resolves with `status: 'queued'` and no `sha`. Bitbucket can't reopen a declined pull request, so `reopen()` rejects for pull requests. ## Comparisons Bitbucket doesn't count the commits of a comparison, so `contents.compare()` reads all of them to give `aheadBy`. Bitbucket sends them newest first, so with `commitLimit`, the provider stops once it has that many, and `aheadBy` is absent when more commits remain. With `files: false`, it doesn't read the changed files at all. ## Participants as reviews Bitbucket has participants who vote on a pull request, and the provider presents them 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. If you pass a body or inline comments, it rejects with `UnsupportedOperationError`. ## Markdown Bitbucket doesn't render HTML elements such as `
`. To make a Markdown body readable there, `forge.normaliseMarkdown(body)` turns each `` into bold text and removes the `
` tags. ## Accounts Bitbucket reads accounts by their UUID or Atlassian account ID, and nicknames aren't unique. For this reason, `users.get(login)` isn't available. ## Webhooks To verify deliveries, set `webhookSecret` to the secret that you configured on the hook. Bitbucket only signs a delivery when the hook has a secret, so deliveries from a hook without one fail verification. ```ts const forge = bitbucket({ webhookSecret: process.env.BITBUCKET_WEBHOOK_SECRET, }).create() const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` With each delivery, Bitbucket sends these headers:
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 doesn't keep a delivery log, so `webhooks.deliveries()` and `webhooks.redeliver()` aren't available. ## Capabilities
Capability Support Without credentials
experimental ❌ ❌
sources.poll ❌ ❌
sources.webhook ✅ ✅
sources.subscribe ❌ ❌
repos.get ✅ ✅
users.get ❌ ❌
users.me ✅ ❌
users.sponsorable ❌ ❌
users.events ❌ ❌
repos.list ✅ ❌
repos.byOwner ✅ ✅
repos.labels ❌ ❌
repos.createLabel ❌ ❌
repos.milestones ❌ ❌
repos.collaborators ❌ ❌
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ❌ ❌
repos.permissionFor ❌ ❌
repos.addCollaborator ❌ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ❌ ❌
repos.events ❌ ❌
orgs.teams ❌ ❌
orgs.teamMembers ❌ ❌
threads.get PR, commit PR, commit
threads.list PR PR
threads.getMany ✅ ✅
threads.events PR, commit PR, commit
comments.list PR, commit PR, commit
comments.get PR (emulated), commit (emulated) PR (unverified), commit (unverified)
comments.edit PR, commit ❌
comments.delete PR, commit ❌
reactions.list ❌ ❌
notifications.list ❌ ❌
notifications.markRead ❌ ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead ❌ ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount ❌ ❌
writes.comment PR, commit ❌
writes.upsertComment PR (emulated), commit (emulated) ❌
writes.close PR ❌
writes.reopen ❌ ❌
writes.create PR ❌
writes.update PR ❌
writes.setLabels ❌ ❌
writes.addLabels ❌ ❌
writes.removeLabels ❌ ❌
writes.setMilestone ❌ ❌
writes.react ❌ ❌
writes.setAssignees ❌ ❌
writes.requestReview PR ❌
writes.merge ✅ ❌
writes.approveAndMerge ✅ ❌
writes.transfer ❌ ❌
writes.markDuplicate ❌ ❌
subscriptions.get ❌ ❌
subscriptions.set ❌ ❌
installations ❌ ❌
checks.thread PR PR
checks.list ✅ ✅
checks.get ❌ ❌
checks.report ✅ ❌
checks.rerun ❌ ❌
ci.runs ❌ ❌
ci.run ❌ ❌
ci.jobs ❌ ❌
ci.job ❌ ❌
ci.log ❌ ❌
contents.file ✅ ✅
contents.tree ✅ ✅
contents.branches ✅ ✅
contents.tags ✅ ✅
contents.resolveRef ✅ ✅
contents.commits ✅ ✅
contents.commit ✅ ✅
contents.compare ✅ ✅
contents.commitFiles ✅ ❌
contents.threadFiles ✅ ✅
contents.threadCommits ✅ ✅
reviews.list emulated emulated
reviews.get emulated emulated
reviews.create emulated ❌
reviews.submit ❌ ❌
reviews.approve emulated ❌
reviews.reply ❌ ❌
reviews.resolveThread ❌ ❌
releases.list ❌ ❌
releases.get ❌ ❌
releases.latest ❌ ❌
releases.getByTag ❌ ❌
releases.downloadAsset ❌ ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.list ✅ ❌
webhooks.create ✅ ❌
webhooks.update ✅ ❌
webhooks.delete ✅ ❌
webhooks.rotateSecret ✅ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ✅ ✅
search.repos ✅ ❌
search.commits ❌ ❌
search.code ❌ ❌
securityAlerts ❌ ❌
eventKinds native native
authKinds token , basic , anonymous token , basic , anonymous
limits unknown unknown
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.