Skip to main content
Use this path when you run Overcut on your own infrastructure and your Bitbucket is self-hosted Bitbucket Server or Data Center (an on-prem instance, not bitbucket.org). You connect with an OAuth 2.0 incoming Application Link created on your Bitbucket instance. Each deployment uses its own client credentials; there is no shared Overcut Cloud client.
Not your setup? See Which setup do I need?. For Atlassian-hosted Bitbucket Cloud, use the Forge app (Overcut Cloud) or direct OAuth (self-hosted Overcut).

​
How it differs from Bitbucket Cloud

Bitbucket Server / Data CenterBitbucket Cloud
OAuth endpointsYour instance ({instance}/rest/oauth2/latest/...)Central (bitbucket.org/site/oauth2/...)
Authorization3LO only (browser consent)3LO or 2LO
ScopesREPO_READ, REPO_WRITEaccount, repository, pullrequest, pipeline, webhook (+write)
REST APIv1.0 (/rest/api/1.0)v2.0
WebhookManual, one project-level webhookAutomatic, per repository
Bitbucket Data Center requires DC 7.21 or newer for the OAuth 2.0 authorization-code provider (any 8.x LTS works).

​
Prerequisites

  • A Bitbucket Server or Data Center instance reachable from your Overcut deployment over HTTPS
  • Administrator access to that instance (to create the Application Link) and project admin on the target project (to create the webhook)
  • A self-hosted Overcut deployment you operate (see Deployment configuration)
The Bitbucket account you authorize with owns every pull request, comment, and merge Overcut performs. Authorize while signed in as a dedicated service account (for example overcut-bot), not your personal admin account. The service account must have write access to the target repositories.

​
Connect

1

Create an OAuth 2.0 incoming Application Link

As a Bitbucket administrator, go to Administration -> Application links -> Create link, and select External application / Incoming.Set the redirect (callback) URL to your deployment’s Overcut callback, exactly:
https://<your-overcut-domain>/bitbucket-server-auth-app/callback
This must match the BITBUCKET_SERVER_REDIRECT_URI server setting character for character, and must use https.In the Application permissions matrix, tick Repositories: Write (this auto-includes Read), which maps to the REPO_READ + REPO_WRITE scopes Overcut requests. Do not tick Admin / Projects / Account / System-admin - webhooks are added manually, so no admin scope is needed. Save, then copy the generated Client ID and Client Secret.
2

Connect in Overcut

In Overcut, open the git providers list and click the Bitbucket Server / Data Center tile. Enter:
  • Instance URL: your Bitbucket base URL (for example https://bitbucket.your-company.com)
  • the Client ID and Client Secret from the previous step
Make sure your browser session is signed into Bitbucket as the service account, then click Authorize. Overcut captures the service-account identity and stores the connection.
3

Register one project-level webhook in Bitbucket

Webhooks are configured in Bitbucket, separately from the Application Link. Open the connected org’s settings page in Overcut (View settings on the provider page) to find the webhook URL (https://<dispatcher>/webhooks/bitbucket/server/<orgId>) and a revealable secret.In Bitbucket, go to Project settings -> Webhooks -> Create webhook (a project-level webhook is inherited by every repository in the project, so this is one paste per project, not per repo). Paste the URL, put the revealed secret in the webhook’s Secret field (it signs the X-Hub-Signature HMAC the dispatcher verifies), and enable these events:
  • pr:opened, pr:from_ref_updated, pr:modified, pr:merged, pr:declined
  • pr:reviewer:approved, pr:reviewer:unapproved, pr:reviewer:needs_work
  • pr:comment:added
Creating a project webhook requires project admin in Bitbucket (a one-time human step); the Overcut OAuth token itself stays write-only.
Bitbucket Data Center has no Pipelines product, so there are no CI/build-status webhook events on this path.

​
Deployment configuration

These settings are configured once by whoever operates the self-hosted Overcut deployment.
SettingValueNotes
INTEGRATION_BITBUCKET_SERVER_ENABLEDtrueSet on both the server and workflow-dispatcher to enable the tile and inbound webhooks.
BITBUCKET_SERVER_REDIRECT_URIhttps://<your-overcut-domain>/bitbucket-server-auth-app/callbackMust equal the Application Link redirect URL exactly.
DISPATCHER_BASE_URLhttps://<dispatcher-or-app>/hooksExternal URL used to build the webhook URL shown in Overcut.

​
Troubleshooting

  • redirect_uri mismatch at Authorize: the Application Link redirect URL and BITBUCKET_SERVER_REDIRECT_URI are not byte-identical (often a trailing slash or http vs https).
  • Token exchange returns 400 (PKCE): some instances require PKCE for the incoming link. Confirm the Application Link is configured to allow the authorization-code grant without mandatory PKCE, or contact Overcut support.
  • Authorize fails to reach Bitbucket: the instance must be reachable from the Overcut deployment over HTTPS with a valid certificate. Confirm network access and TLS.
  • 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.
  • Webhook events never fire: confirm the webhook secret in Bitbucket matches the one shown in Overcut, the listed PR events are enabled, and DISPATCHER_BASE_URL is set to the external URL with INTEGRATION_BITBUCKET_SERVER_ENABLED=true on the dispatcher.
For concepts shared across all Bitbucket setups (pull request operations, webhook behavior, ticket links), see the Bitbucket overview.