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.

Access token permissions

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

When using campaigns the access token needs write permissions on the project and repository level. See "Code host interactions in campaigns" 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 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. Note the webhook URL displayed below the Update repositories button.
  7. On your Bitbucket Server 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 and use them to sync pull request events, used by campaigns, faster 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.

Internal rate limits

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

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). If rate limiting is configured more than once for the same code host instance, the most restrictive limit will be used.

NOTE Internal rate limiting is only currently applied when synchronising campaign changesets.

Configuration

Bitbucket Server 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 repository permissions.
	"authorization": null,

	// TLS certificate of the Bitbucket Server 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 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 instance.
	//
	// If "http", Sourcegraph will access Bitbucket Server repositories using Git URLs of the form http(s)://bitbucket.example.com/scm/myproject/myrepo.git (using https: if the Bitbucket Server instance uses HTTPS).
	//
	// If "ssh", Sourcegraph will access Bitbucket Server 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"

	// Defines whether repositories from this Bitbucket Server instance should be enabled and cloned when they are first seen by Sourcegraph. If false, the site admin must explicitly enable Bitbucket Server repositories (in the site admin area) to clone them and make them searchable on Sourcegraph. If true, they will be enabled and cloned immediately (subject to rate limiting by Bitbucket Server); site admins can still disable them explicitly, and they'll remain disabled.
	"initialRepositoryEnablement": false,

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

	// Configuration for Bitbucket Server Sourcegraph plugin
	"plugin": 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 repository.
	//
	//  - "{host}" is replaced with the Bitbucket Server 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 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 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 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 personal access token with Read permissions. When using campaigns, 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 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.
	"token": null,

	// URL of a Bitbucket Server 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 instance. Also set the corresponding "token" or "password" field.
	"username": null,

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