---
title: "Bitbucket"
description: "Bitbucket Cloud pull requests and review threads in the same shapes as every other forge. No issues there to read."
canonical_url: "https://forges.agntn.dev/platforms/bitbucket"
---
# Bitbucket

> Bitbucket Cloud pull requests and review threads in the same shapes as every other forge. No issues there to read.

<platform-facts platform="bitbucket">



</platform-facts>

## 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`.

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      Endpoint
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Repositories and tags
    </td>
    
    <td>
      <code>
        GET …
      </code>
      
      , <code>
        GET /repositories/:workspace
      </code>
      
      , <code>
        GET …/refs/tags
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pull requests
    </td>
    
    <td>
      <code>
        GET …/pullrequests
      </code>
      
       with a state filter, <code>
        GET …/pullrequests/:id
      </code>
      
      , <code>
        POST …/pullrequests
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Pull request files, checks and timeline
    </td>
    
    <td>
      <code>
        GET …/pullrequests/:id/diffstat
      </code>
      
      , <code>
        GET …/pullrequests/:id/statuses
      </code>
      
      , <code>
        GET …/pullrequests/:id/activity
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Conversation comments
    </td>
    
    <td>
      <code>
        GET …/pullrequests/:id/comments?q=(deleted=false) AND (inline.path=null)
      </code>
      
      , <code>
        POST …/comments
      </code>
      
      , <code>
        PUT
      </code>
      
       and <code>
        DELETE …/comments/:id
      </code>
      
       after a read
    </td>
  </tr>
  
  <tr>
    <td>
      Review threads
    </td>
    
    <td>
      <code>
        GET …/pullrequests/:id/comments
      </code>
      
      , <code>
        POST …/pullrequests/:id/comments
      </code>
      
       with <code>
        parent
      </code>
      
       for replies, <code>
        POST
      </code>
      
       or <code>
        DELETE …/pullrequests/:id/comments/:id/resolve
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Commits and checks
    </td>
    
    <td>
      <code>
        GET …/commits
      </code>
      
      , <code>
        GET …/commit/:sha
      </code>
      
       with <code>
        GET …/diffstat/:sha
      </code>
      
      , <code>
        GET …/commit/:sha/statuses
      </code>
      
       after ref resolution
    </td>
  </tr>
  
  <tr>
    <td>
      Repository contents
    </td>
    
    <td>
      <code>
        GET …/commit/:ref
      </code>
      
      , then <code>
        GET …/src/:sha/:path?format=meta
      </code>
      
      , then the raw file or directory listing
    </td>
  </tr>
</tbody>
</table>

## 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`.


## Sitemap

See the full [sitemap](https://forges.agntn.dev/sitemap.md) for all pages.
