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 set this up, add Bitbucket Server as an external service to Sourcegraph:

  1. Go to User menu > Site admin.
  2. Open the External services page.
  3. Press + Add external service.
  4. Enter a Display name (using “Bitbucket Server” is OK if you only have one Bitbucket Server instance).
  5. In the Kind menu, select Bitbucket Server.
  6. Configure the connection to Bitbucket Server in the JSON editor. Use Cmd/Ctrl+Space for completion, and see configuration documentation below.
  7. Press Add external service.

Repository syncing

There are four fields for configuring which repositories are mirrored:

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.

SSH cloning is not used, so you don’t need to configure SSH cloning.

Configuration

Bitbucket Server external service connections support the following configuration options, which are specified in the JSON editor in the site admin external services area.

{
	// 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`
	"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"
	//     },
	//     {
	//       "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,

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

	// 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 scope. 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
}