Platforms

Bitbucket

Bitbucket Cloud pull requests and review threads in the same shapes as every other forge. No issues there to read.
IDbitbucket04 / 08api.bitbucket.org/2.0
Platform / bitbucket

Bitbucket

Spoken by BitbucketProvider. Same resources, same shapes, its own quirks kept inside.

Access

CreatecreateProvider("bitbucket")

Importimport { BitbucketProvider } from"@agntn/forges/bitbucket"

EnvBITBUCKET_TOKEN, BITBUCKET_API_TOKEN, BITBUCKET_EMAIL

CLInone, there's no Bitbucket CLI login

Header
Bearer or Basic
Anonymous
public repositories, until a 429 a handful of requests in
Threads
inline comments with their replies, resolvable
Code search
unsupported, explicit error
Templates
none

Address a Bitbucket workspace

ts
import { createProvider } from "@agntn/forges";

const bitbucket = await createProvider("bitbucket", { token: process.env.BITBUCKET_TOKEN });

const pull = { owner: "atlassian", repo: "atlassian-connect-express", number: 527 };
const { items: threads } = await bitbucket.threads.list(pull);
const readme = await bitbucket.repos.readContents(pull, { path: "README.md" });

owner means workspace, and repo means repository slug. Each must be a single path segment. Something like ../admin gets a 400 before any request.

The default API base is https://api.bitbucket.org/2.0. Set baseURL to override it. forges adds /2.0 when it's missing.

Where does the token come from?

@agntn/credentials/bitbucket checks an explicit token first. Then it checks BITBUCKET_TOKEN, an access token sent as a bearer.

Finally, it checks BITBUCKET_API_TOKEN and BITBUCKET_EMAIL together. That Atlassian API token uses Basic auth, with the email as login. The API token alone doesn't count.

For an explicit API token, pass username beside token:

ts
createProvider("bitbucket", { token, username: "you@example.com" });

Without username, an explicit token goes as a bearer. There's no Bitbucket CLI login to check.

Pass { token: "" } for anonymous reads. Public repositories work without a token, but probing hit a 429 after a handful of calls. A token is the sane choice.

What it reads

Endpoints are relative to /2.0. In the table, … means /repositories/:workspace/:slug.

ResourceEndpoint
Repositories and tagsGET …, GET /repositories/:workspace, GET …/refs/tags
Pull requestsGET …/pullrequests with a state filter, GET …/pullrequests/:id, POST …/pullrequests
Pull request files, checks and timelineGET …/pullrequests/:id/diffstat, GET …/pullrequests/:id/statuses, GET …/pullrequests/:id/activity
Conversation commentsGET …/pullrequests/:id/comments?q=(deleted=false) AND (inline.path=null), POST …/comments, PUT and DELETE …/comments/:id after a read
Review threadsGET …/pullrequests/:id/comments, POST …/pullrequests/:id/comments with parent for replies, POST or DELETE …/pullrequests/:id/comments/:id/resolve
Commits and checksGET …/commits, GET …/commit/:sha with GET …/diffstat/:sha, GET …/commit/:sha/statuses after ref resolution
Repository contentsGET …/commit/:ref, then GET …/src/:sha/:path?format=meta, then the raw file or directory listing

What comes back

  • Bitbucket keeps conversation and inline comments together. The inline field distinguishes them. pullRequests.listComments returns only conversation, using a filter on Bitbucket's server. That keeps pages full.
  • A thread starts with an inline comment and includes every reply, oldest first. Its ID is the opening comment's ID, because Bitbucket resolves that comment. Replies to replies stay in the right thread.
  • isResolved comes from the opening comment's resolution object. isOutdated is always false because Bitbucket doesn't say.
  • line points to the new side. For a removed line, it uses the old side instead.
  • Deleted comments remain in Bitbucket's list with empty bodies. forges drops them. A deleted reply disappears, and a deleted opening comment takes its thread with it. Even Bitbucket's ghosts have empty speech bubbles.
  • threads.reply posts under the newest comment. The reply lands at the bottom.
  • Comment author.login is the Bitbucket nickname.
  • Directory entries have size for files and null for directories and symlinks. Listing stops after ten pages, with entriesComplete: false.
  • A file over 1 MiB is a 413 from the metadata alone. Its bytes never leave Bitbucket.
  • File reads pin the ref to its resolved commit. A continuation with an offset above zero must pass that SHA. A moving branch can't splice versions together.
  • Pull request checks come from build statuses. Pipelines report there too.
  • Pagination follows Bitbucket's next link in the response body. nextCursor carries that link.

Gotchas

Why does resolving need a read first?

  • Bitbucket returns 409 when you resolve an already resolved thread. It returns 404 when you reopen an open one. That's annoying. forges reads the state first and returns the thread unchanged, so resolving twice is harmless.
  • The commit log filters by ref and path only. since or until would come back ignored, so they're a 501 instead of a quietly wrong list.
  • Thread listing reads every comment page, 100 comments at a time. Conversation and review comments share that list.

What isn't there

Each operation below returns a ForgesError with status 501 and a sentence, before any request. An agent can stop instead of retrying.

Bitbucket Cloud has no issue tracker or releases, so issues.* and releases.* return 501. ciRuns.list also returns 501 and points to pull request or commit checks instead. users.get by username returns 501 because Bitbucket profiles use account IDs, not names.

Code search, templates, reactions, issue fields and sub issues return 501 too. Zero open issues, forever. Nice dashboard.

Some gaps are ours, not Bitbucket's. Editing or merging a pull request, reviews, search, commit comparison, patches and review comment edits aren't wired up here yet. Same 501, same sentence.

Where it lives

The provider lives in src/providers/bitbucket.ts. It uses the forges/bitbucket adapter and gets tokens from @agntn/credentials/bitbucket.