bitbucket.org). Instead of
the managed Forge app, you connect directly with your own OAuth consumer.
Each deployment brings its own credentials; there is no shared Overcut Cloud
client.
Not your setup? See Which setup do I need?.
On Overcut Cloud, use the Forge app
instead. For on-prem Bitbucket, see Bitbucket Server / Data Center.
Prerequisites
- A Bitbucket Cloud workspace, with admin access to Workspace settings -> OAuth consumers
- A self-hosted Overcut deployment you operate (see Deployment configuration)
Choose an authorization type
The connect modal has an Authorization type toggle:- User authorization (3LO) - the default, covered by the steps below. A browser Authorize step runs once, signed in as the service account. Bitbucket issues a refresh token so the connection survives long-running sessions.
- Service account (2LO) - no browser consent. Recommended for headless setups or when an org policy blocks interactive authorization. See Use a service account (2LO).
Connect with user authorization (3LO)
Create an OAuth consumer in Bitbucket
In Bitbucket, go to Workspace settings -> OAuth consumers -> Add consumer
and name it (for example This must match the
Overcut).Set the Callback URL to your deployment’s Overcut callback, exactly:BITBUCKET_CLOUD_REDIRECT_URI server setting character
for character, and must use https (except http://localhost:<port> for
local development).Leave the consumer non-private
Leave “This is a private consumer” unchecked. This is required so Bitbucket
issues a refresh token; without it, the connection breaks on long-running
sessions.
Enable the permissions
Enable these permissions on the consumer:
- Account: Read
- Repositories: Read + Write
- Pull requests: Read + Write
- Pipelines: Read
- Webhooks: Read and write (required so Overcut can register webhooks automatically)
Connect in Overcut
In Overcut, open the git providers list and click the Bitbucket Cloud
(self-hosted connect) tile. Leave the authorization type as User
authorization (3LO). Enter your Workspace slug (for example
acme) and
the Key and Secret from the previous step.Make sure your browser session is signed into Bitbucket as the service
account, then click Authorize. Overcut verifies workspace access,
captures the bot identity, and stores the connection.Add repositories (webhooks are automatic)
Add repositories to Overcut as usual. For each registered repository, Overcut
automatically registers a webhook on the Bitbucket repo for pull request,
push, and commit-status events, signed with a per-repo secret. There is no
webhook URL to paste. Removing a repository (or disconnecting the workspace)
removes its webhook.
Use a service account (2LO)
Use this when you prefer a headless credential over a browser consent, or when an org policy blocks interactive authorization. 2LO authenticates as the OAuth consumer itself (no consenting user), so there is no callback and no Authorize step.Create a private OAuth consumer
In Workspace settings -> OAuth consumers -> Add consumer, create a
private consumer (check “This is a private consumer”). A callback URL
is not required for 2LO.Enable the same permissions as the 3LO path - Repositories (Read +
Write), Pull requests (Read + Write), Pipelines (Read), and
Webhooks (Read and write) - then copy the Key and Secret.
The 2LO token authenticates as the OAuth consumer itself - a
service-account-style principal, not a human user - so there is no account to
sign in as and no browser consent. Overcut attributes its actions to the
consumer and uses that identity for bot-loop prevention. Create the consumer
in the workspace that owns the target repositories.
Connect in Overcut
Open the Bitbucket Cloud (self-hosted connect) tile and switch the
Authorization type to Service account (2LO). Enter the Workspace
slug plus the consumer’s Key and Secret, and click Connect.There is no callback URL and no browser Authorize step. The token acts as
the consumer owner; scopes come from the consumer’s configuration. 2LO has no
refresh token, so Overcut renews by re-requesting.
Deployment configuration
These settings are configured once by whoever operates the self-hosted Overcut deployment.| Setting | Value | Notes |
|---|---|---|
INTEGRATION_BITBUCKET_CLOUD_ENABLED | true | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. |
BITBUCKET_CLOUD_REDIRECT_URI | https://<your-overcut-domain>/bitbucket-cloud-auth-app/callback | Must equal the consumer Callback URL exactly (3LO only). |
DISPATCHER_BASE_URL | https://<dispatcher-or-app>/hooks | External URL used to build the auto-registered webhook URL. |
JWT_SECRET (shared
by the server that registers the hook and the dispatcher that verifies it), so no
separate webhook secret is required.
Troubleshooting
redirect_urimismatch at Authorize: the consumer Callback URL andBITBUCKET_CLOUD_REDIRECT_URIare not byte-identical (often a trailing slash orhttpvshttps).- “The authorized account cannot access workspace …” after consent: the account you authorized with is not a member of the workspace you entered, or the slug is wrong.
- Actions attributed to the wrong person, or bot loops: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account.
- Auth fails on long sessions (“no refresh token”): the 3LO consumer was created as a private consumer, so Bitbucket never issued a refresh token. Recreate it with “This is a private consumer” unchecked and reconnect. (A private consumer is correct only for 2LO.)
- Webhook events never fire: confirm
DISPATCHER_BASE_URLis the external URL and the dispatcher hasINTEGRATION_BITBUCKET_CLOUD_ENABLED=true; check the repo’s webhooks in Bitbucket for the auto-registered Overcut hook.