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
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:
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.
| Resource | Endpoint |
|---|---|
| Repositories and tags | GET …, GET /repositories/:workspace, GET …/refs/tags |
| Pull requests | GET …/pullrequests with a state filter, GET …/pullrequests/:id, POST …/pullrequests |
| Pull request files, checks and timeline | GET …/pullrequests/:id/diffstat, GET …/pullrequests/:id/statuses, GET …/pullrequests/:id/activity |
| Conversation comments | GET …/pullrequests/:id/comments?q=(deleted=false) AND (inline.path=null), POST …/comments, PUT and DELETE …/comments/:id after a read |
| Review threads | GET …/pullrequests/:id/comments, POST …/pullrequests/:id/comments with parent for replies, POST or DELETE …/pullrequests/:id/comments/:id/resolve |
| Commits and checks | GET …/commits, GET …/commit/:sha with GET …/diffstat/:sha, GET …/commit/:sha/statuses after ref resolution |
| Repository contents | GET …/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
inlinefield distinguishes them.pullRequests.listCommentsreturns 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.
isResolvedcomes from the opening comment'sresolutionobject.isOutdatedis alwaysfalsebecause Bitbucket doesn't say.linepoints 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.replyposts under the newest comment. The reply lands at the bottom.- Comment
author.loginis the Bitbucket nickname. - Directory entries have
sizefor files andnullfor directories and symlinks. Listing stops after ten pages, withentriesComplete: 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
nextlink in the response body.nextCursorcarries 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.
sinceoruntilwould 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.