Connect Bitbucket Cloud

Only users with the Admin role can connect Bitbucket. ArchGuard supports Bitbucket Cloud. Bitbucket Data Center is planned but not available. For GitHub, see Connect GitHub. An organization uses one provider at a time.

Create a Workspace Access Token

  1. In Bitbucket, open your workspace settings and create a workspace access token.
  2. Give it these permissions:
Scope Why ArchGuard needs it
repository (read) List repositories, read the diff and the ADR folder.
repository:write Commit approved ADR files, and set commit build statuses.
pullrequest Read pull requests and post the summary comment.
webhook Register and remove the webhooks.
  1. Copy the token. Bitbucket shows it once.

These scopes come from Atlassian's API reference for the calls ArchGuard makes. They have not yet been confirmed against your workspace. If Validate and connect succeeds but enabling a repository or a commit fails with a permission message, add the missing scope and paste the token again.

Connect

  1. Open Settings and choose Bitbucket Cloud as the provider.
  2. Enter the workspace slug, which is the first part of your repository URLs (bitbucket.org/<slug>/...).
  3. Paste the token and select Validate and connect.

ArchGuard checks the token against the workspace, stores it encrypted (AES-256-GCM), and syncs the repositories the token can see. Syncing normally finishes in a few seconds. Select Sync now later to pick up new repositories.

The token is never displayed again. To rotate it, paste a new one and select Replace token and sync.

What the connection can and cannot do

  • ArchGuard can only see repositories that the token's workspace grants.
  • New repositories start disabled. See Enable repositories.
  • Removing the token from Bitbucket stops all evaluations. Pull requests will keep their last build status.

Errors you may see

Message Meaning
The access token was rejected (401) The token is wrong, expired or revoked.
The token lacks repository read scope (403) Add the repository scope.
Workspace not found (404) Check the workspace slug.
Could not reach Bitbucket Network or Bitbucket outage. Try again.

More help: Troubleshooting and FAQ.