Bitbucket Integration

Last updated: June 24, 2026

Aisle connects to Bitbucket Cloud using an API token scoped to a workspace. This article covers the connection flow, the exact scopes required, and how to set up a dedicated bot account.

Prerequisites

A Bitbucket Cloud user with admin access on the workspace and the projects you want Aisle to see. We recommend a dedicated bot account, not a personal account, so your integration survives staff changes.
The bot account's email address (Bitbucket requires this on token creation).
Admin access in Aisle to add the VCS connection.

Generate the API token

Sign in to Bitbucket as the bot account.
Go to Personal settings → API tokens (top-right menu).
Click Create API token.
Name it aisle-fe and select the scopes below.
Generate, copy, and store the token securely.

Required scopes

Scope	Why
`read:user:bitbucket`	Identify the bot account.
`read:workspace:bitbucket`	List workspaces.
`read:project:bitbucket`	List projects in a workspace.
`read:repository:bitbucket`	Clone and read repository contents.
`read:pullrequest:bitbucket`	Read PR metadata.
`read:webhook:bitbucket`	Read existing webhooks.
`read:pipeline:bitbucket`	Read pipeline (CI) statuses.
`write:repository:bitbucket`	Push fix branches.
`write:webhook:bitbucket`	Register Aisle's webhook on imported repos.
`write:pullrequest:bitbucket`	Open fix PRs and post PR comments.
`delete:webhook:bitbucket`	Remove the webhook when a repo is deleted from Aisle.

These match the scope set Aisle requests internally; if any are missing, the corresponding feature will fail with a 403 on the Bitbucket side and surface as a setup error in Aisle.

Connect in Aisle

In Aisle, go to Integrations → VCS Connections and click Bitbucket.
Provide:
- Integration Name — bitbucket-prod or similar.
- Account Email — the email of the bot account (required by Bitbucket API).
- Access Token — paste the token.
Save.

After connecting

Import repositories from Repositories → Import Repositories.
Enable the Aisle Analyzer on each repo.
For CI integration, Aisle reads Bitbucket Pipelines status on the linked PR — there's no separate setup beyond the scopes above.

Rotating the token

Bitbucket API tokens don't auto-renew. Plan rotation:

Create a new token with the same scopes.
Update the connection in Aisle.
Revoke the old token.

If the old token is revoked before the new one is in place, the connection will briefly show Invalid token and queued webhooks may need manual redelivery.

Troubleshooting

Symptom	What to check
Invalid token	The Account Email matches the token owner; the token hasn't been revoked.
Repositories don't appear	Workspace and project scopes — make sure the bot account is a member of the projects, not just the workspace.
Fix PRs fail to open	The token has `write:pullrequest:bitbucket`; the target branch isn't protected against the bot account.
Webhook deliveries failing	Check the repo's Repository settings → Webhooks — Aisle's webhook should be active and delivering 2xx. Bitbucket retries failed deliveries automatically for a limited time.