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:
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.
There are four fields for configuring which repositories are mirrored:
repos
projectKey/repositorySlug
format.repositoryQuery
none
, all
), and/or a Bitbucket Server Repo Search Request Query Parameters.exclude
repos
, and repositoryQuery
fields.excludePersonalRepositories
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:
"webhooks"
property to "plugin"
(you can generate a secret with openssl rand -hex 32
):"plugin": {"webhooks": {"secret": "verylongrandomsecret"}}
global
pr, repo
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.
By default, all Sourcegraph users can view all repositories. To configure Sourcegraph to use Bitbucket Server's repository permissions, see Repository permissions.
With the Sourcegraph Bitbucket Server plugin you can enable fast permission syncing:
"plugin.permissions"
property:{ // [...] "plugin": { "permissions": "enabled" } }
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.
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.
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 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.
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" // }, // { // "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" // ] // 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, // DEPRECATED: Switch to "plugin.webhooks" "webhooks": null }