bitbucket_server.md

Bitbucket Server

Site admins can sync Git repositories hosted on Bitbucket Server (and the Bitbucket Data Center deployment option) with Sourcegraph so that users can search and navigate the repositories.

To connect Bitbucket Server to Sourcegraph:

1. Go to Site admin > Manage repositories > Add repositories
2. Select Bitbucket Server.
3. Configure the connection to Bitbucket Server using the action buttons above the text field, and additional fields can be added using Cmd/Ctrl+Space for auto-completion. See the configuration documentation below.
4. Press Add repositories.

Also consider installing the Sourcegraph Bitbucket Server plugin which enables native code intelligence for every Bitbucket user when browsing code and reviewing pull requests, allows for faster permission syncing between Sourcegraph and Bitbucket Server and adds support for webhooks to Bitbucket Server.

Repository syncing

There are four fields for configuring which repositories are mirrored:

• repos
  A list of repositories in projectKey/repositorySlug format.
• repositoryQuery
  A list of strings with some pre-defined options (none, all), and/or a Bitbucket Server Repo Search Request Query Parameters.
• exclude
  A list of repositories to exclude which takes precedence over the repos, and repositoryQuery fields.
• excludePersonalRepositories
  With this enabled, Sourcegraph will exclude any personal repositories from being imported, even if it has access to them.

Webhooks

The Sourcegraph Bitbucket Server plugin enables the Bitbucket Server instance to send webhooks to Sourcegraph.

Using webhooks is highly recommended when using Campaigns, since they speed up the syncing of pull request data between Bitbucket Server and Sourcegraph and make it more efficient.

To set up webhooks:

1. Connect Bitbucket Server to Sourcegraph (see instructions above).
2. Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server instance.
3. In Sourcegraph, go to Site admin > Manage repositories and edit the Bitbucket Server configuration.
4. Add the "webhooks" property to "plugin" (you can generate a secret with openssl rand -hex 32):
   "plugin": {"webhooks": {"secret": "verylongrandomsecret"}}
5. Click Update repositories.
6. Sourcegraph now automatically creates a webhook on your Bitbucket Server instance with the name sourcegraph-, followed by the unique ID of your Sourcegraph instance. It is configured to deliver pr and repo events.
7. On your Bitbucket Server instance, go to Administration > Add-ons > Sourcegraph and make sure that the new sourcegraph-campaigns webhook is listed under All webhooks with a timestamp in the Last successful column.

Done! Sourcegraph will now receive webhook events from Bitbucket Server and use them to sync pull request events, used by Campaigns, fast and more efficiently.

Repository permissions

By default, all Sourcegraph users can view all repositories. To configure Sourcegraph to use Bitbucket Server's repository permissions, see Repository permissions.

Fast permission syncing

With the Sourcegraph Bitbucket Server plugin you can enable fast permission syncing:

1. Connect Bitbucket Server to Sourcegraph (see instructions above).
2. Follow the instructions to set up repository permissions with Bitbucket Server.
3. Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server instance.
4. In Sourcegraph, go to Site admin > Manage repositories and edit the Bitbucket Server configuration.
5. Add the "plugin.permissions" property:

{
  // [...]
  "plugin": {
    "permissions": "enabled"
  }
}

Authentication for older Bitbucket Server versions

Bitbucket Server versions older than v5.5 require specifying a less secure username and password combination, as those versions of Bitbucket Server do not support personal access tokens.

HTTPS cloning

Sourcegraph by default clones repositories from your Bitbucket Server via HTTP(S), using the access token or account credentials you provide in the configuration. The username field is always used when cloning, so it is required.

Repository labels

Sourcegraph will mark repositories as archived if they have the archived label on Bitbucket Server. You can exclude these repositories in search with archived:no search syntax.

Configuration

Bitbucket Server connections support the following configuration options, which are specified in the JSON editor in the site admin "Manage repositories" area.

[View page on docs.sourcegraph.com](https://docs.sourcegraph.com/admin/external_service/bitbucket_server) to see rendered content.