The Sourcegraph plugin for Bitbucket Server communicates with your Sourcegraph instance to add code intelligence to your Bitbucket Server code views and pull requests.
The plugin also has the optional functionality to enable faster ACL permission syncing between Sourcegraph and Bitbucket Server and can add webhooks with configurable scope to Bitbucket Server.
- Bitbucket Data Center 9.0.0–9.6.5: use the published
plugin 3.0.2
security update. GCS
latest.jarand3.0.2.jarserve the same verified bytes;3.0.1.jarpreserves the previous release. Maintain 3.x on the3.xbranch, notmaster. - Bitbucket Data Center 10.0.2–10.5.2: use the published plugin 4.0.0, which uses Java 21 and Jakarta and requires Sourcegraph 8.2.0 or later. Do not install the Bitbucket 9 JAR or merely widen its compatibility bounds.
Upgrade Sourcegraph to 8.2.0 or later before installing plugin 4.0.0. That release includes the Bitbucket browser adapter and Git bearer-token cloning fixes. Installing the JAR does not update your Sourcegraph instance's integration bundle. See development and release guidance for verification and publishing.
Bitbucket 10 disables Basic authentication by default. Use bearer PATs for REST.
Git HTTP also needs a Sourcegraph release with Bitbucket bearer-token cloning;
older Sourcegraph versions send the token using Basic authentication. Alternatively,
configure the connector with gitURLType: "ssh" and gitSSHCredential. Do not
re-enable Basic authentication just to work around an older connector.
- Plugin 4.0.0 requires a Sourcegraph instance running 8.2.0 or later. The historical v3.6 minimum applies only to older plugin versions, not Bitbucket 10.
- Your Sourcegraph instance should have a Bitbucket Server code host connection configured.
- The
corsOriginproperty should be set in site configuration to include the URL of your Bitbucket Server instance. Example value:
"corsOrigin": "https://bitbucket.example.com"Via the Atlassian marketplace
- Log into your Bitbucket instance as an admin.
- Click the admin dropdown and choose Add-ons.
- Click Find new apps or Find new add-ons from the left-hand side of the page.
- Locate "Sourcegraph for Bitbucket" via search.
- Click Install to download and install your app.
The URL below is for Bitbucket 9 only. For Bitbucket 10, prefer the compatible Marketplace release, or an explicitly versioned 4.x artifact with an approved signature and trusted verification certificate. Bitbucket 10 enables UPM signature verification by default; do not disable it to install this plugin.
- Log in to Bitbucket Server as an admin.
- Navigate to the Bitbucket admin page.
- Go to Add-ons > Manage apps.
- Click Upload app
- In the From this URL field, paste the following URL:
https://storage.googleapis.com/sourcegraph-for-bitbucket-server/latest.jar
This URL serves plugin 3.0.2 for Bitbucket 9. For Bitbucket 10, install 4.0.0
through Marketplace; the GCS 4.0.0.jar archive is not a signed direct-install
alternative without a separately approved signature and trusted certificate.
Upgrade Sourcegraph to 8.2.0 or later first, then follow Atlassian's Bitbucket upgrade procedure and install plugin 4.0.0 from Marketplace. Bitbucket disables user-installed apps during the major upgrade, so the replacement plugin may remain disabled. In Manage apps, select Sourcegraph for Bitbucket and click Enable if needed. Check the Sourcegraph URL and existing webhooks; both were preserved in our upgrade tests. Fresh installations enable automatically.
Installing the Sourcegraph for Bitbucket Server via the Atlassian marketplace will automatically update the plugin to the latest version, if enabled, and offer new versions to administrators in the UI.
Follow the steps in Installation.
After installing the Sourcegraph for Bitbucket Server, you need to configure it to point to your Sourcegraph instance.
- On Bitbucket, go to the Administration page
- Find the Sourcegraph entry under Add-ons:
- On the Sourcegraph Settings page, set the Sourcegraph URL to the URL of your Sourcegraph instance:
Once configured, Sourcegraph for Bitbucket Server adds code intelligence hovers (with Go to definition and Find references) to code views and pull requests for all users that are logged in to your self-hosted Sourcegraph instance. It also adds links to view repositories, files and diffs on Sourcegraph.
The plugin loads this integration from your Sourcegraph instance, so it changes when you upgrade Sourcegraph, not when you upgrade the plugin.
If a user is not logged in to Sourcegraph, they will still see the "View Repository on Sourcegraph" links, but code intelligence hovers will not be displayed.
The plugin sends webhooks that can be scoped globally, to a project, or to a repository, instead of Bitbucket's per-repository webhooks. Sourcegraph uses them to update repositories after pushes and to keep Batch Changes changesets current.
- In Sourcegraph, create an incoming webhook for your Bitbucket Server code host connection (see Incoming webhooks).
- In Bitbucket, go to Administration > Add-ons > Sourcegraph and add a webhook with scope
global, the incoming webhook's URL as the endpoint, and its secret. - Subscribe to
repo:refs_changedfor repository updates and, for Batch Changes,repo:build_status,pr:activity, andpr:participant:status.
See the webhooks/README.md for the event names, payloads, and REST API.
When the Bitbucket Server code host connection sets "plugin": {"permissions": "enabled"}, Sourcegraph fetches repository permissions from the plugin instead of paging through Bitbucket's REST API (see Fast permission syncing). The plugin adds two endpoints under /rest/sourcegraph-admin/1.0:
/permissions/repositories?permission=<PERMISSION_LEVEL>
Returns a list of repository IDs the authenticated user has access to on the givenpermissionlevel. Sourcegraph calls this endpoint./permissions/users?repository=<PROJECT_KEY>/<REPO_SLUG>&permission=<PERMISSION_LEVEL>
Returns a list of user IDs that have access to the given repository on the givenpermissionlevel. Requires a system admin.
PERMISSION_LEVEL is read, write, or admin. The lists returned by both endpoints are encoded as Roaring Bitmaps.


