Bitbucket Cloud

Supported on Enterprise plans.

Available via the Web app.

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. Go to Site admin > Manage code hosts > Add repositories.
  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.

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 (workspaces) 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.

Configuration options

Bitbucket Cloud code host connections can be configured with either a username and app password combination, or with workspace access tokens.

Username and app password

  1. Visit your Bitbucket account settings page.
  2. Navigate to App passwords.
  3. Select Create app password.
  4. Give your app password a label.
  5. Select the Projects: Read permission. Repositories: Read should automatically be selected.
  6. Press Create.

Use the newly created app password and your username to configure the Bitbucket Cloud connection:

JSON
{
  "url": "https://bitbucket.org",
  "username": "USERNAME",
  "appPassword": "<PASSWORD>",
  // ... other settings
}

Workspace access token

  1. Visit the Bitbucket Cloud workspace settings page of the workspace you want to create an access token for.
  2. Navigate to Security > Access tokens.
  3. Press Create workspace access token.
  4. Give your access token a name.
  5. Select the Projects: Read permission. Repositories: Read should automatically be selected.
  6. Press Create.

Use the newly created access token to configure the Bitbucket Cloud connection:

JSON
{
  "url": "https://bitbucket.org",
  "accessToken": "ACCESS_TOKEN",
  // ... other settings
}

HTTPS cloning

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

Rate limits

Read about how Bitbucket Cloud applies rate limits here.

When Sourcegraph encounters rate limits on Bitbucket Cloud, it will retry the request with exponential back-off, until 5 minutes have passed. If the connection is still being rate limited after 5 minutes, the request will be dropped.

Internal rate limits

See Internal rate limits

User authentication

To configure Bitbucket Cloud as an authentication provider (which will enable sign-in via Bitbucket Cloud), see the authentication documentation.

Repository permissions

Prerequisite: Add Bitbucket Cloud as an authentication provider.

Then, add or edit a Bitbucket Cloud connection as described above and include the authorization field:

JSON
{
  // The URL used to set up the Bitbucket Cloud authentication provider must match this URL.
  "url": "https://bitbucket.com",
  "username": "horsten",
  "appPassword": "$APP_PASSWORD",
  // ...
  "authorization": {}
}

NOTE: It can take some time to complete full cycle of repository permissions sync if you have a large number of users or repositories. See sync duration time for more information.

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/code_hosts/bitbucket_cloud.schema.json

JSON
{
	// The workspace access token to use when authenticating with Bitbucket Cloud.
	"accessToken": null,
 
	// 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,
 
	// If non-null, enforces Bitbucket Cloud repository permissions. This requires that there is an item in the [site configuration json](https://sourcegraph.com/docs/admin/config/site_config#auth-providers) `auth.providers` field, of type "bitbucketcloud" with the same `url` field as specified in this `BitbucketCloudConnection`.
	"authorization": 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 git@bitbucket.org:myteam/myproject.git. See the documentation for how to provide SSH private keys and known_hosts: https://sourcegraph.com/docs/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
}

Configuration Notes

Bitbucket Cloud connections provide streamlined configuration for cloud-hosted repositories:

  • Authentication Options: Support for both username/app password and workspace access tokens
  • Repository Selection: Uses teams for workspace-based syncing and exclude for filtering unwanted repositories
  • Path Patterns: The repositoryPathPattern field uses {host} and {nameWithOwner} variables for repository naming
  • Workspace Access: Workspace access tokens provide more granular control than user-based app passwords

Authentication Methods

Bitbucket Cloud supports two primary authentication approaches:

  • Username/App Password: User-scoped access with app passwords created in personal settings
  • Workspace Access Token: Workspace-scoped access tokens with fine-grained permissions
  • Projects/Repositories Permissions: Both methods require Projects: Read and Repositories: Read permissions

Rate Limiting Configuration

Bitbucket Cloud connections include rate limiting for API management:

  • Default: 7,200 requests per hour with rate limiting enabled
  • Bitbucket Cloud enforces API request limits based on plan type
  • Sourcegraph implements exponential backoff for rate limit handling

Security Considerations

Authentication Security

App Passwords: Provide user-level access with specific permissions:

  • Create app passwords with minimal required permissions (Projects: Read, Repositories: Read)
  • Use dedicated service accounts rather than personal accounts when possible
  • App passwords inherit the user's repository access permissions
  • Regularly audit and rotate app passwords

Workspace Access Tokens: Provide workspace-level access control:

  • More secure than user-based app passwords for organizational use
  • Scoped to specific workspaces, limiting access surface
  • Support fine-grained permissions for better security posture
  • Recommended for production deployments

Repository Permissions

Bitbucket Cloud permission syncing considerations:

  • Permission syncing requires Bitbucket Cloud as an authentication provider
  • User access is determined by their Bitbucket Cloud account permissions
  • Workspace access tokens provide read-only access to repositories
  • OAuth flow ensures proper user authentication and authorization

HTTPS Security

Bitbucket Cloud connections use HTTPS by default:

  • All API communication is encrypted using TLS
  • Git operations use HTTPS with authentication credentials
  • SSH access is supported but requires additional key configuration
  • No custom certificate configuration needed for cloud service

Common Examples

Basic Team Sync with App Password

JSON
{
  "url": "https://bitbucket.org",
  "username": "sourcegraph-bot",
  "appPassword": "ATBBxxxxxxxxxxxxxxxxxx",
  "teams": [
    "engineering-team",
    "platform-team"
  ]
}

Workspace Access Token Configuration

JSON
{
  "url": "https://bitbucket.org",
  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx",
  "teams": ["my-workspace"],
  "exclude": [
    {"name": "my-workspace/legacy-project"},
    {"pattern": "^.*-archive$"}
  ]
}

SSH Access with Custom Path Pattern

JSON
{
  "url": "https://bitbucket.org",
  "username": "deployment-user",
  "appPassword": "ATBBxxxxxxxxxxxxxxxxxx",
  "teams": ["mobile-apps"],
  "gitURLType": "ssh",
  "repositoryPathPattern": "bitbucket/{nameWithOwner}"
}

Repository Permissions with OAuth

JSON
{
  "url": "https://bitbucket.org",
  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx",
  "teams": ["enterprise-workspace"],
  "authorization": {},
  "exclude": [
    {"name": "enterprise-workspace/internal-docs"}
  ]
}

High-volume Configuration with Rate Limiting

JSON
{
  "url": "https://bitbucket.org",
  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx", 
  "teams": ["large-organization"],
  "rateLimit": {
    "enabled": true,
    "requestsPerHour": 5000
  },
  "webhookSecret": "your-webhook-secret-here"
}

Best Practices

Authentication Management

  1. Use workspace access tokens for production deployments instead of personal app passwords
  2. Create dedicated service accounts when using username/app password authentication
  3. Apply least-privilege principles by granting only necessary permissions
  4. Regularly audit token usage and rotate credentials periodically

Repository Organization

  1. Organize by workspaces using the teams field to sync relevant repositories
  2. Use exclusion patterns to filter out archived, experimental, or sensitive repositories
  3. Implement consistent naming with repositoryPathPattern for better organization
  4. Monitor workspace changes as team membership affects repository access

Performance Optimization

  1. Configure appropriate rate limits to stay within Bitbucket Cloud's API limits
  2. Use workspace access tokens for better rate limit handling
  3. Monitor API usage to avoid hitting plan-based limits
  4. Optimize team selections to sync only necessary repositories

Security Management

  1. Enable repository permissions by configuring Bitbucket Cloud as an auth provider
  2. Use workspace access tokens for better security isolation
  3. Implement webhook security with strong shared secrets
  4. Regularly review team membership to ensure appropriate repository access

Maintenance

  1. Monitor connection health through the site admin interface
  2. Review team configurations as organizational structure changes
  3. Update exclusion patterns when repository naming conventions change
  4. Test authentication changes in staging environments before production deployment

Webhooks

Using the webhooks property on the external service has been deprecated.

Please consult this page in order to configure webhooks.