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

  1. In Bitbucket, open the workspace, select the Settings cog, then Workspace settings.

  2. In the sidebar, under Apps and features, select OAuth clients, then Add client.

  3. Enter a name, for example Span. Bitbucket requires a callback URL, but Span doesn't use it, so any URL works (for example https://example.com).

  4. Mark the client as private.

  5. Grant Account: Read, Repositories: Read, and Pull requests: Read.

  6. Save, then select the client's name to show its Key and Secret.

Step 3: Connect in Span

  1. Go to Settings → Integrations and click Connect on the Bitbucket Cloud card.

  2. Workspace: enter only the slug from Step 1, for example acme. Don't paste the full URL.

  3. Client ID: paste the client's Key.

  4. Client secret: paste the client's Secret.

  5. 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 (acme, not https://bitbucket.org/acme/). If it still fails, create the client in that same workspace

"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

Supported integrations

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.