Bitbucket
Connects workspaces to repositories in a Bitbucket Cloud workspace. Bitbucket Data Center (self-hosted) is not supported.
Connecting a workspace
Go to Settings → Version control → Bitbucket, enter your Bitbucket workspace slug and an access token, and click Connect.
The slug is the name in your Bitbucket URL. For bitbucket.org/my-team/my-repo, the slug is my-team. Enter it exactly: Bitbucket no longer lets an app list the workspaces you belong to, so a wrong slug can only be reported as "not reachable" rather than corrected for you.
Creating the token
Use a workspace access token, created in Bitbucket under your workspace's Settings → Access tokens. One workspace token reaches every repository in the workspace, so connecting once is all that is needed.
Grant these permissions:
- Repositories: Write
- Pull requests: Write
- Webhooks: Read and write
We check these when you connect and name any that are missing, so a token that is too narrow is caught at the form rather than when the first pull request opens.
It must be an access token. App passwords are no longer accepted by Bitbucket, and a user API token will not work. An access token also belongs to the workspace rather than to a person, so compliance comments and checks are attributed to the token and keep working when people join or leave.
Connect one workspace per connection. To add a second Bitbucket workspace, repeat the steps.
Plans
Workspace and project access tokens require a Bitbucket Premium plan, which is also required to make the compliance check block a merge.
On a lower plan, use a repository access token instead. It is the same connection, with a smaller reach: only the repository the token was created on. The connection says which kind of token it holds, so a short repository list is legible rather than confusing.
| Token | Reaches | Plan |
|---|---|---|
| Workspace | Every repository in the workspace | Premium |
| Project | Every repository in one project | Premium |
| Repository | One repository | Any |
What you get
- Repository access to list, connect, and create repositories
- Two-way sync between the workspace and Bitbucket
- Pull request support to create, comment on, and merge pull requests
- Compliance checks posted to pull requests as commit build statuses
If a connection stops working
The connection shows Authorization no longer valid. Remove it and connect again. This happens when the authorization is revoked in Bitbucket, when the token is deleted, or when a connection sits unused for about three months.