Bitbucket access tokens

Bitbucket Cloud supports three levels of access token for authenticating API and Git operations. CloudBees Unify can use any of these token types to connect to your Bitbucket Cloud repositories.

For instructions on configuring a Bitbucket integration in CloudBees Unify, refer to SCM integrations: Bitbucket.

Token types and hierarchy

Bitbucket Cloud access tokens follow a containment hierarchy:

Workspace access token (WAT): grants access to all projects and repositories in a workspace.
Project access token (PAT): grants access to all repositories in a single project.

Project access token support has not been fully validated. Where possible, use a repository or workspace access token for production workflows.
Repository access token (RAT): grants access to a single repository.

The hierarchy is: Workspace > Project > Repository (broadest to narrowest scope).

Project and Workspace access tokens are a Bitbucket Cloud Premium feature. Bitbucket permits Standard plan customers to generate Repository access tokens only.

Which token type to use

Table 1. Token type by use case
Use case	Recommended token type	Notes
Single repository integration	Repository access token	One token per repository.
Multiple repositories in one project	Project access token	Supports `repository:write` scope. Suitable for workflows that need to commit workflow YAML.
Multiple repositories with full workflow support	Workspace access token	Supports all CloudBees Unify operations including committing workflow YAML files back to repositories.
Triggering Bitbucket Pipelines	Any token type	Requires `pipeline:write` scope, available on all three token types.

Required scopes

Table 2. Required Bitbucket scopes per CloudBees Unify operation
CloudBees Unify operation	Required Bitbucket scope	Repository token	Project token	Workspace token
Git checkout (clone)	`repository` (read)	Yes	Yes	Yes
SCM integration, commit workflow YAML	`repository:write`	Yes	Yes	Yes
Create webhooks	`webhook`	Yes	Yes	Yes
Run a Bitbucket pipeline	`pipeline:write`	Yes	Yes	Yes

Project access tokens support repository:write as of February 2023. All three token types can be used for workflows that commit YAML back to repositories.

Workspace field

When you configure a Bitbucket integration with a Project or Workspace access token, you must provide the Workspace slug in the integration form. The workspace slug is the value that appears in your Bitbucket URL: https://bitbucket.org/<workspace-slug>.

For existing integrations that have already onboarded at least one repository, the workspace is auto-populated by the hourly repository sync process. No manual action is required for these integrations.

Token expiration

Bitbucket access tokens have a configurable expiration date. Set an expiration date that aligns with your organization’s security policies. To rotate a token, create a new token in Bitbucket with the same scopes and update the corresponding CloudBees Unify secret.