Bitbucket Cloud

Site admins can sync Git repositories hosted on Bitbucket Cloud with Sourcegraph so that users can search and navigate the repositories.

To connect Bitbucket Cloud to Sourcegraph:

  1. Depending on whether you are a site admin or user:
    1. Site admin: Go to Site admin > Manage code hosts > Add repositories
    2. User: Go to Settings > Manage hosts.
  2. Select Bitbucket.org.
  3. Configure the connection to Bitbucket Cloud using the action buttons above the text field. Additional fields can be added using Cmd/Ctrl+Space for auto-completion. See the configuration documentation below.
  4. Press Add repositories.

NOTE That adding code hosts as a user is currently in private beta.

Repository syncing

Currently, all repositories belonging to the user configured will be synced.

In addition, there is one more field for configuring which repositories are mirrored:

  • teams
    A list of teams that the configured user has access to whose repositories should be synced.
  • exclude
    A list of repositories to exclude, which takes precedence over the teams field.

HTTPS cloning

Sourcegraph clones repositories from your Bitbucket Cloud via HTTP(S), using the username and appPassword required fields you provide in the configuration.

Internal rate limits

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

If enabled, the default rate is set at 7200 per hour (2 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 synchronizing changesets in batch changes, repository permissions, and repository metadata from code hosts.

Configuration

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

admin/external_service/bitbucket_cloud.schema.json

{
	// The API URL of Bitbucket Cloud, such as https://api.bitbucket.org. Generally, admin should not modify the value of this option because Bitbucket Cloud is a public hosting platform.
	"apiURL": null,
	// Other example values:
	// - "https://api.bitbucket.org"

	// The app password to use when authenticating to the Bitbucket Cloud. Also set the corresponding "username" field.
	"appPassword": null,

	// A list of repositories to never mirror from Bitbucket Cloud. Takes precedence over "teams" configuration.
	//
	// Supports excluding by name ({"name": "myorg/myrepo"}) or by UUID ({"uuid": "{fceb73c7-cef6-4abe-956d-e471281126bd}"}).
	"exclude": null,
	// Other example values:
	// - [
	//     {
	//       "name": "myorg/myrepo"
	//     },
	//     {
	//       "uuid": "{fceb73c7-cef6-4abe-956d-e471281126bc}"
	//     }
	//   ]
	// - [
	//     {
	//       "name": "myorg/myrepo"
	//     },
	//     {
	//       "name": "myorg/myotherrepo"
	//     },
	//     {
	//       "pattern": "^topsecretproject/.*"
	//     }
	//   ]

	// The type of Git URLs to use for cloning and fetching Git repositories on this Bitbucket Cloud.
	//
	// If "http", Sourcegraph will access Bitbucket Cloud repositories using Git URLs of the form https://bitbucket.org/myteam/myproject.git.
	//
	// If "ssh", Sourcegraph will access Bitbucket Cloud repositories using Git URLs of the form [email protected]:myteam/myproject.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"

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

	// The pattern used to generate the corresponding Sourcegraph repository name for a Bitbucket Cloud repository.
	//
	//  - "{host}" is replaced with the Bitbucket Cloud URL's host (such as bitbucket.org),  and "{nameWithOwner}" is replaced with the Bitbucket Cloud repository's "owner/path" (such as "myorg/myrepo").
	//
	// For example, if your Bitbucket Cloud is https://bitbucket.org and your Sourcegraph is https://src.example.com, then a repositoryPathPattern of "{host}/{nameWithOwner}" would mean that a Bitbucket Cloud repository at https://bitbucket.org/alice/my-repo is available on Sourcegraph at https://src.example.com/bitbucket.org/alice/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}/{nameWithOwner}",

	// An array of team names identifying Bitbucket Cloud teams whose repositories should be mirrored on Sourcegraph.
	"teams": null,
	// Other example values:
	// - ["name"]
	// - [
	//     "kubernetes",
	//     "golang",
	//     "facebook"
	//   ]

	// URL of Bitbucket Cloud, such as https://bitbucket.org. Generally, admin should not modify the value of this option because Bitbucket Cloud is a public hosting platform.
	"url": null,
	// Other example values:
	// - "https://bitbucket.org"

	// The username to use when authenticating to the Bitbucket Cloud. Also set the corresponding "appPassword" field.
	"username": null,

	// A shared secret used to authenticate incoming webhooks (minimum 12 characters).
	"webhookSecret": null
}

Webhooks

To set up authentication for webhooks, set the webhookSecret setting, which is then used to authenticate incoming webhook requests to /.api/bitbucket-cloud-webhooks.

{
  "webhookSecret": "verylongrandomsecret"
}

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

To set up webhooks:

  1. In Sourcegraph, go to Site admin > Manage code hosts and edit the Bitbucket Cloud configuration.
  2. Add the "webhookSecret" property to the configuration (you can generate a secret with openssl rand -hex 32):
    "webhookSecret": "verylongrandomsecret"
  3. Click Update repositories.
  4. Copy the webhook URL displayed below the Update repositories button.
  5. On Bitbucket Cloud, go to each repository, and then Repository settings > Webhooks.
  6. Click Add webhook.
  7. Fill in the webhook form:
    • Title: any title.
    • URL: the URL you copied above from Sourcegraph.
    • Triggers: select Build status created and Build status updated under Repository, and every item under Pull request.
  8. Click Save.
  9. Confirm that the new webhook is listed below Repository hooks.

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