# Bitbucket

> Connect Bitbucket Cloud for the Coder: access token or Atlassian token, the exact permissions for each step, where to paste it, and common fixes.

Connect Bitbucket and the Coder reads your repository, its pull requests, and its build results, copies the repository into its own [workspace](/docs/workspaces/files), and hands you a pull request for review. When your [house rules](/docs/ceo/house-rules) allow it, it can also merge.

> [!IMPORTANT]
> Today you connect Bitbucket in the **StellarFirm desktop app**. On stellarfirm.ai you can browse [Integrations](https://stellarfirm.ai/app/integrations) and read what each tool does; connecting from the web is Coming soon.

## At a glance

| | |
| --- | --- |
| Category | Source control |
| Status | Available |
| Used by | Coder (available now) |
| Connect in | The StellarFirm desktop app, under Integrations |
| What you paste | An access token, or an Atlassian token with its account email |
| Works with | Bitbucket Cloud (bitbucket.org) |

> [!WARNING]
> Bitbucket switched app passwords off in June 2026. They no longer work anywhere, including here. Use one of the two tokens below.

## Pick a token

| | Repository access token | Atlassian token with scopes |
| --- | --- | --- |
| Acts as | Its own member of one repository | You |
| Reaches | One repository | Every repository your account can reach |
| Issues | No: access tokens have no issue permission | Yes, with the issue scopes |
| What you paste | The token only | The token and your Atlassian account email |
| Where you can use it | Every Bitbucket plan | Every Bitbucket plan |

A repository access token is the narrowest choice and is enough for pull requests. Choose the Atlassian token if you want the Coder to read or open Bitbucket issues. On the Premium plan you can also create a project or workspace access token, which works like a repository token across many repositories.

## What assistants can do

| Ability | How it runs | Repository access token | Atlassian token scope |
| --- | --- | --- | --- |
| Read the repository and copy it into its workspace | Reads on its own | Repositories: Read | `read:repository:bitbucket` |
| Read pull requests and changed files | Reads on its own | Pull requests: Read | `read:pullrequest:bitbucket` |
| Read build results | Reads on its own | Repositories: Read | `read:repository:bitbucket` |
| Read issues | Reads on its own | Not possible | `read:issue:bitbucket` |
| Push a branch with its work | Waits for your Approve | Repositories: Write | `write:repository:bitbucket` |
| Open a pull request, a draft by default | Waits for your Approve | Pull requests: Write | `write:pullrequest:bitbucket` |
| Open an issue | Waits for your Approve | Not possible | `write:issue:bitbucket` |
| Merge a pull request | Only as your [merge policy](/docs/ceo/house-rules#merge-policy) allows | Pull requests: Write | `write:pullrequest:bitbucket` |

Issues also need the repository's own issue tracker turned on, under the repository's **Settings**, **Features**. The Coder cannot create Bitbucket repositories. Create the repository yourself, then give it to the Coder.

## Create a repository access token

1. On bitbucket.org, open the repository.
2. Select **...** next to the repository name, then **Settings**.
3. Under **Security**, select **Access tokens**, then **Create access token**.
4. Name it, such as "StellarFirm Coder", and choose when it expires. When it expires, the Coder stops as **Blocked** and asks you for a new one.
5. Under permissions, tick **Repositories: Write** and **Pull requests: Write**. Bitbucket ticks the matching Read for you.
6. Select **Create** and copy the token. Bitbucket shows it once.

## Create an Atlassian token with scopes

1. In Bitbucket, select your profile picture in the upper right, then **Account settings**.
2. On your Atlassian account page, open the **Security** tab and select **Create and manage API tokens**.
3. Select **Create API token with scopes**. Give it a name and an expiry date, then **Next**.
4. Choose **Bitbucket** as the app, then **Next**.
5. Select these scopes, then **Next**:
   - `read:repository:bitbucket` and `write:repository:bitbucket`
   - `read:pullrequest:bitbucket` and `write:pullrequest:bitbucket`
   - `read:issue:bitbucket` and `write:issue:bitbucket`
6. Select **Create token** and copy it. It is shown once.
7. Note the email of your Atlassian account. You can see it in Bitbucket under **Personal settings**, **Email aliases**.

## Connect it in StellarFirm

1. Open the StellarFirm desktop app and sign in.
2. Open **Integrations** and pick **Bitbucket**.
3. Paste the token into **Access token**.
4. For an Atlassian token only, enter your **Atlassian account email**. Leave it empty for a repository access token.
5. Leave **Use live Bitbucket** on and press **Connect**.
6. The card shows **Connected**. Your token is saved on your computer by the desktop app, never shown back to you, and handed to one git command at a time.

## Tell the Coder where to work

The Coder needs a repository, written as `workspace/repository`.

- **In your message.** Name it, or paste its link: "Coder, in acme/web, fix the login redirect."
- **For good, per Coder.** Open **Settings**, **Coders**, edit the Coder, and under **Repository and login** choose **Bitbucket** as source control and fill in **Repository**. See [several Coders](/docs/personas/coder#several-coders).

Each Coder can also use its own login. Choose **Its own login**, paste a token, and add the Atlassian account email only if it is an Atlassian token. A repository access token on its own is enough.

## Good to know

- **Pushing and merging follow your house rules.** The Coder pushes to a new branch of its own, never to your default branch, and never force pushes. Pushing waits for your Approve. Merging follows your [merge policy](/docs/ceo/house-rules#merge-policy): review only by default, never while builds are failing or still running, and always with a merge commit that keeps the branch. Your branch restrictions on Bitbucket still apply.
- **Drafts cannot be merged.** Open the pull request on Bitbucket and select **Mark as ready** before you ask the Coder to merge.
- **"Pick up the top ticket" needs issues.** With a repository access token, or with the issue tracker off, name the work in your message instead.
- **If the clone fails**, the job stops as **Blocked** before any coding and says what to fix.
- **Several code hosts connected?** A link or the word Bitbucket in your message picks Bitbucket.
- **Bitbucket Data Center** is not supported.
- **Revoke at any time.** Revoke the token in Bitbucket and the Coder loses access straight away. Then choose **Turn off** on the Bitbucket card.

## Troubleshooting

| What you see | What it means | What to do |
| --- | --- | --- |
| Blocked: the Coder cannot clone the repository | The token cannot see it, or has expired | Check the repository path and the token's expiry. A repository access token only reaches its own repository |
| 401 Unauthorized with an Atlassian token | The email is missing or wrong, or you pasted an old app password | Enter the email of the Atlassian account that made the token, or create a new token |
| 403 Forbidden on a push or pull request | A permission is missing | Give Repositories: Write and Pull requests: Write, or the matching write scopes |
| Issues cannot be read or opened | Access tokens have no issue permission, or the issue tracker is off | Use an Atlassian token with the issue scopes and turn on issues for the repository |
| The merge is refused | The pull request is a draft, a build is not green, or a branch restriction blocks it | Mark it as ready, wait for the builds, or adjust the restriction |

## Prompts

```prompt title="Build a change"
Coder, Bitbucket is connected. In [workspace]/[repository], add [feature]. Run the tests and open a pull request for review once I Approve.
```

```prompt title="Summarise open pull requests"
Coder, list the open pull requests on [workspace]/[repository], say which ones are stuck, and what each is waiting for.
```

```prompt title="Check a build"
Coder, read the latest build results on [workspace]/[repository] and tell me whether the main branch is healthy.
```

## Next

- [Connect your code](/docs/getting-started/connect-your-code): the checklist for every code host.
- [House rules](/docs/ceo/house-rules) and [approvals](/docs/ceo/approvals): what waits for you.
- [GitHub](/docs/integrations/github) and [GitLab](/docs/integrations/gitlab).

---

Source: https://stellarfirm.ai/docs/integrations/bitbucket