Bitbucket Cloud Integration
Last updated: November 17, 2026
Span's Bitbucket Cloud integration syncs pull requests, commits, and repository activity from your Bitbucket Cloud workspace to power code review, cycle time, and developer productivity metrics. It connects through a private OAuth client that you create in Bitbucket. Bitbucket Data Center is not supported.
Why it matters
Bitbucket is the source for your pull request and commit metrics in Span. Connecting the right workspace with read-only permissions means Span sees the repositories you want measured, without tying the connection to any one person's account.
How it works
OAuth client: Span connects with the key and secret of a private OAuth client created in your workspace. No personal account, password, or app password is involved.
Read-only: the client needs Account: Read, Repositories: Read, and Pull requests: Read. Write or admin also work, since they include read.
One Bitbucket Cloud workspace per Span organization.
Checked on connect: before saving, Span confirms the client has the permissions above and can read the workspace.
Setup
Step 1: Find your workspace slug
The slug is the part of your Bitbucket URL right after bitbucket.org/. For https://bitbucket.org/acme/, the slug is acme. You can also find it in Bitbucket under Workspace settings, in the Workspace ID field.
Step 2: Create an OAuth client in Bitbucket
In Bitbucket, open the workspace, select the Settings cog, then Workspace settings.
In the sidebar, under Apps and features, select OAuth clients, then Add client.
Enter a name, for example
Span. Bitbucket requires a callback URL, but Span doesn't use it, so any URL works (for examplehttps://example.com).Mark the client as private.
Grant Account: Read, Repositories: Read, and Pull requests: Read.
Save, then select the client's name to show its Key and Secret.
Step 3: Connect in Span
Go to Settings → Integrations and click Connect on the Bitbucket Cloud card.
Workspace: enter only the slug from Step 1, for example
acme. Don't paste the full URL.Client ID: paste the client's Key.
Client secret: paste the client's Secret.
Click Continue. Once connected, the Bitbucket Cloud connection lists your workspace's repositories.
You need the Manage Integrations permission in Span. Owners, Admins, and the Integration Admins group have it by default.
Things to know
The connection stays tied to its workspace. Reconnecting can't point it at a different workspace. To measure another workspace, contact support.
Permission changes apply right away. If Span reports a missing permission, add it to the client in Bitbucket and click Continue again. You don't need a new key or secret.
Renaming the Workspace ID changes your slug. If you rename it in Bitbucket, reconnect the Bitbucket Cloud integration with the new slug.
Span syncs every repository in the workspace. To limit it to certain repositories, contact support.
Troubleshooting
Symptom | Likely cause | Resolution |
|---|---|---|
"Could not read the workspace … Check the slug and that the OAuth client belongs to that workspace." | The Workspace field holds a URL instead of the slug, or the client was created in another workspace | Enter only the slug ( |
"The OAuth client is missing permission(s): …" | The client lacks one of the read permissions | Add the permissions named in the message to the clientmer, save, and click Continue again |
"Could not authenticate with the provided client ID and secret." | Wrong key or secret, or the client isn't private | Copy the Key and Secret again with no extra spaces, and mark the client as private |
"The authorization server is rate limiting requests." | Too many attempts in a short time | Wait a minute and click Continue again |
Related articles
How to create an Integrations Admin in Span
Troubleshooting integration connection status
Need help?
Contact your Span account team or reach out to support@span.app.