Bitbucket Cloud

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.

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.

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:<uuid>. 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 <details>. forge.normaliseMarkdown(body) turns each <summary> into bold text and removes the <details> 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.

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:

Bitbucket has no delivery log, so webhooks.deliveries() and webhooks.redeliver() are unavailable.

Recording fixtures

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.