Bitbucket access tokens

Connect Bitbucket Cloud with an access token when a workflow should act as an integration rather than as the person who connected it. An access token belongs to a workspace, project, or repository, not to a user, so it keeps working when people leave and its reach is limited to what it was created for.

Bitbucket shows actions taken with the token (comments, merges, pipeline runs) under the token's name.

Prerequisites

Admin access to the workspace, project, or repository the token is for. Workspace and project access tokens require a Bitbucket Cloud Premium plan; repository access tokens do not.

Create the access token

1. 1

   Open the repository, project, or workspace settings in Bitbucket Cloud and go to Access tokens

2. 2

   Click Create access token and give it a name (e.g. Sim workflows) — this is the name Bitbucket shows on everything the workflow does

3. 3

   Select Repositories: Read (repository). Add Pull requests, Repositories: Write, or Pipelines scopes for the actions the workflow takes

4. 4

   Create the token and copy it right away — Bitbucket shows it only once

Add the access token to Sim

1. 1

   Open Integrations from your workspace sidebar

2. 2

   Search for "Bitbucket" and open it, then click Add to Sim and choose Add access token

3. 3

   Paste the token and enter a repository it can read as workspace/repository (the my-workspace/my-repository in bitbucket.org/my-workspace/my-repository). For a repository access token, that is its own repository

4. 4

   Click Add access token. Sim verifies the token by reading that repository once, so the token needs the repository scope

Use the credential in workflows

Add a Bitbucket block and select the saved access token in the account dropdown, then choose the workspace and repository. The block calls api.bitbucket.org with the token, exactly as it does with a connected account.

Two things need a signed-in account and do not work with an access token:

• List Workspaces lists the workspaces of the person who connected the account, so Sim refuses to run it with an access token. Use a connected account for it.
• The workspace picker lists a person's workspaces, so it cannot load them for an access token. Switch the workspace field to manual entry and type the slug.

Rotate tokens and handle permission failures

If validation succeeds but an action fails, the token is likely missing that action's scope, or the repository is outside the token's project or repository. Access tokens cannot be edited after creation: create a replacement with the right scopes, update the credential in Sim, test the workflow, and then revoke the old token. See Bitbucket's access token documentation.