Bitbucket Server / Bitbucket Data Center

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

To connect Bitbucket Server / Bitbucket Data Center to Sourcegraph:

  1. Go to Site admin > Manage repositories > Add repositories
  2. Select Bitbucket Server / Bitbucket Data Center.
  3. Configure the connection to Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center and adds support for webhooks to Bitbucket Server / Bitbucket Data Center.

Access token permissions

Sourcegraph requires a Bitbucket Server / Bitbucket Data Center personal access token with read permissions to sync repositories.

When using batch changes the access token needs write permissions on the project and repository level. See “Code host interactions in batch changes” for details.

You can create a personal access token at https://[your-bitbucket-hostname]/plugins/servlet/access-tokens/add. Also set the corresponding username field.

For Bitbucket Server instances that don’t support personal access tokens (Bitbucket Server version 5.4 and older), specify user-password credentials in the username and password fields.

Repository syncing

There are four fields for configuring which repositories are mirrored:

Webhooks

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

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

To set up webhooks:

  1. Connect Bitbucket Server / Bitbucket Data Center to Sourcegraph (see instructions above).
  2. Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server / Bitbucket Data Center instance.
  3. In Sourcegraph, go to Site admin > Manage repositories and edit the Bitbucket Server / Bitbucket Data Center 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. Note the webhook URL displayed below the Update repositories button.
  7. On your Bitbucket Server / Bitbucket Data Center instance, go to Administration > Add-ons > Sourcegraph
  8. Fill in the Add a webhook form
    • Name: A unique name representing your Sourcegraph instance
    • Scope: global
    • Endpoint: The URL from step 6
    • Events: pr, repo
    • Secret: The secret you configured in step 4
  9. Confirm that the new webhook is listed under All webhooks with a timestamp in the Last successful column.

Done! Sourcegraph will now receive webhook events from Bitbucket Server / Bitbucket Data Center and use them to sync pull request events, used by batch changes, faster and more efficiently.

Repository permissions

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

Fast permission syncing

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

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

Authentication for older Bitbucket Server / Bitbucket Data Center versions

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

HTTPS cloning

Sourcegraph by default clones repositories from your Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center. You can exclude these repositories in search with archived:no search syntax.

Internal rate limits

Internal rate limiting can be configured to limit the rate at which requests are made from Sourcegraph to Bitbucket Server / Bitbucket Data Center.

If enabled, the default rate is set at 28,800 per hour (8 per second) which can be configured via the requestsPerHour field (see below):

  • For Sourcegraph <=3.38, if rate limiting is configured more than once for the same code host instance, the most restrictive limit will be used.
  • For Sourcegraph >=3.39, rate limiting should be enabled and configured for each individual code host connection.

NOTE Internal rate limiting is only currently applied when synchronising changesets in batch changes, repository permissions and repository metadata from code hosts.

Configuration

Bitbucket Server / Bitbucket Data Center connections support the following configuration options, which are specified in the JSON editor in the site admin “Manage repositories” area.

admin/external_service/bitbucket_server.schema.json

{
	// If non-null, enforces Bitbucket Server / Bitbucket Data Center repository permissions.
	"authorization": null,

	// TLS certificate of the Bitbucket Server / Bitbucket Data Center instance. This is only necessary if the certificate is self-signed or signed by an internal CA. To get the certificate run `openssl s_client -connect HOST:443 -showcerts < /dev/null 2> /dev/null | openssl x509 -outform PEM`. To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"certificate": null,
	// Other example values:
	// - "-----BEGIN CERTIFICATE-----\n..."

	// A list of repositories to never mirror from this Bitbucket Server / Bitbucket Data Center instance. Takes precedence over "repos" and "repositoryQuery".
	//
	// Supports excluding by name ({"name": "projectKey/repositorySlug"}) or by ID ({"id": 42}).
	"exclude": null,
	// Other example values:
	// - [
	//     {
	//       "name": "myproject/myrepo"
	//     },
	//     {
	//       "id": 42
	//     }
	//   ]
	// - [
	//     {
	//       "name": "myproject/myrepo"
	//     },
	//     {
	//       "name": "myproject/myotherrepo"
	//     },
	//     {
	//       "name": "~USER/theirrepo"
	//     },
	//     {
	//       "pattern": "^topsecretproject/.*"
	//     }
	//   ]

	// Whether or not personal repositories should be excluded or not. When true, Sourcegraph will ignore personal repositories it may have access to. See https://docs.sourcegraph.com/integration/bitbucket_server#excluding-personal-repositories for more information.
	"excludePersonalRepositories": false,

	// The type of Git URLs to use for cloning and fetching Git repositories on this Bitbucket Server / Bitbucket Data Center instance.
	//
	// If "http", Sourcegraph will access Bitbucket Server / Bitbucket Data Center repositories using Git URLs of the form http(s)://bitbucket.example.com/scm/myproject/myrepo.git (using https: if the Bitbucket Server / Bitbucket Data Center instance uses HTTPS).
	//
	// If "ssh", Sourcegraph will access Bitbucket Server / Bitbucket Data Center repositories using Git URLs of the form ssh://[email protected]/myproject/myrepo.git. See the documentation for how to provide SSH private keys and known_hosts: https://docs.sourcegraph.com/admin/repo/auth#repositories-that-need-http-s-or-ssh-authentication.
	"gitURLType": "http",
	// Other example values:
	// - "ssh"

	// Deprecated and ignored field which will be removed entirely in the next release. BitBucket repositories can no longer be enabled or disabled explicitly.
	"initialRepositoryEnablement": false,

	// The password to use when authenticating to the Bitbucket Server / Bitbucket Data Center instance. Also set the corresponding "username" field.
	//
	// For Bitbucket Server / Bitbucket Data Center instances that support personal access tokens (Bitbucket Server / Bitbucket Data Center version 5.5 and newer), it is recommended to provide a token instead (in the "token" field).
	"password": null,

	// Configuration for Bitbucket Server / Bitbucket Data Center Sourcegraph plugin
	"plugin": null,

	// An array of project key strings that defines a collection of repositories related to their associated project keys
	"projectKeys": null,

	// Rate limit applied when making background API requests to BitbucketServer.
	"rateLimit": {
		"enabled": true,
		"requestsPerHour": 28800
	},

	// An array of repository "projectKey/repositorySlug" strings specifying repositories to mirror on Sourcegraph.
	"repos": null,
	// Other example values:
	// - [
	//     "myproject/myrepo",
	//     "myproject/myotherrepo",
	//     "~USER/theirrepo"
	//   ]

	// The pattern used to generate the corresponding Sourcegraph repository name for a Bitbucket Server / Bitbucket Data Center repository.
	//
	//  - "{host}" is replaced with the Bitbucket Server / Bitbucket Data Center URL's host (such as bitbucket.example.com)
	//  - "{projectKey}" is replaced with the Bitbucket repository's parent project key (such as "PRJ")
	//  - "{repositorySlug}" is replaced with the Bitbucket repository's slug key (such as "my-repo").
	//
	// For example, if your Bitbucket Server / Bitbucket Data Center is https://bitbucket.example.com and your Sourcegraph is https://src.example.com, then a repositoryPathPattern of "{host}/{projectKey}/{repositorySlug}" would mean that a Bitbucket Server / Bitbucket Data Center repository at https://bitbucket.example.com/projects/PRJ/repos/my-repo is available on Sourcegraph at https://src.example.com/bitbucket.example.com/PRJ/my-repo.
	//
	// It is important that the Sourcegraph repository name generated with this pattern be unique to this code host. If different code hosts generate repository names that collide, Sourcegraph's behavior is undefined.
	"repositoryPathPattern": "{host}/{projectKey}/{repositorySlug}",
	// Other example values:
	// - "{projectKey}/{repositorySlug}"

	// An array of strings specifying which repositories to mirror on Sourcegraph. Each string is a URL query string with parameters that filter the list of returned repos. Examples: "?name=my-repo&projectname=PROJECT&visibility=private".
	//
	// The special string "none" can be used as the only element to disable this feature. Repositories matched by multiple query strings are only imported once. Here's the official Bitbucket Server / Bitbucket Data Center documentation about which query string parameters are valid: https://docs.atlassian.com/bitbucket-server/rest/6.1.2/bitbucket-rest.html#idp355
	"repositoryQuery": [
		"none"
	],
	// Other example values:
	// - [
	//     "?name=my-repo\u0026projectname=PROJECT\u0026visibility=private"
	//   ]

	// A Bitbucket Server / Bitbucket Data Center personal access token with Read permissions. When using batch changes, the token needs Write permissions. Create one at https://[your-bitbucket-hostname]/plugins/servlet/access-tokens/add. Also set the corresponding "username" field.
	//
	// For Bitbucket Server / Bitbucket Data Center instances that don't support personal access tokens (Bitbucket Server / Bitbucket Data Center version 5.4 and older), specify user-password credentials in the "username" and "password" fields.
	"token": null,

	// URL of a Bitbucket Server / Bitbucket Data Center instance, such as https://bitbucket.example.com.
	"url": null,
	// Other example values:
	// - "https://bitbucket.example.com"

	// The username to use when authenticating to the Bitbucket Server / Bitbucket Data Center instance. Also set the corresponding "token" or "password" field.
	"username": null,

	// DEPRECATED: Switch to "plugin.webhooks"
	"webhooks": null
}