Bitbucket Server/Bitbucket Data Center

Supported on Enterprise plans.

Available via the Web app.

Site admins can sync Git repositories hosted on Bitbucket Server or Bitbucket Data Center with Sourcegraph so that users can search and navigate their repositories.

To connect Bitbucket Server / Bitbucket Data Center to Sourcegraph:

  1. Go to Site admin > Manage code hosts > Add repositories
  2. Select Bitbucket Server / Bitbucket Data Center.
  3. Configure the connection to Bitbucket Server / Bitbucket Data Center 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 navigation for every Bitbucket user when browsing code and reviewing pull requests, allows for faster permission syncing between Sourcegraph and Bitbucket Server / Bitbucket Data Center and adds support for webhooks to Bitbucket Server / Bitbucket Data Center.

Access token permissions

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

When using batch changes the access token needs write permissions on the project and repository level. See "Code host interactions in batch changes" 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

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

Please consult this page in order to configure webhooks.

Repository permissions

Enforcing Bitbucket Server / Bitbucket Data Center permissions can be configured via the authorization setting in its configuration.

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.

NOTE: Sourcegraph can only sync permissions for personal repositories on Bitbucket Server / Bitbucket Data Center when the Sourcegraph Bitbucket Server plugin is installed.

Prerequisites

  1. You have the exact same user accounts, with matching usernames, in Sourcegraph and Bitbucket Server / Bitbucket Data Center. This can be accomplished by configuring an external authentication provider that mirrors user accounts from a central directory like LDAP or Active Directory. The same should be done on Bitbucket Server / Bitbucket Data Center with external user directories.
  2. Ensure you have set auth.enableUsernameChanges to false in the site config to prevent users from changing their usernames and escalating their privileges.

Setup

Repository permissions for Bitbucket Server / Bitbucket Data Center can be configured via OAuth1 or OAuth2. OAuth2 is the recommended method.

OAuth2

You'll first need to configure Bitbucket Server as an auth provider. Next, in your Bitbucket Server code host connection, add the following authorization settings:

JSON
{
  // Other config goes here
  "authorization": {
    "oauth2": true
  }
}

Once a user has connected their Bitbucket Server account, either by signing-in via Bitbucket Server or by connecting the account on their Settings > Account security page, their OAuth token will be used to sync their repository permissions.

OAuth1

This section walks you through the process of setting up an Application Link between Sourcegraph and Bitbucket Server / Bitbucket Data Center and configuring the Sourcegraph Bitbucket Server / Bitbucket Data Center configuration with authorization settings. It assumes the above prerequisites are met.

As an admin user, go to the "Application Links" page. You can use the sidebar navigation in the admin dashboard, or go directly to https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks.

NOTE: There has been some changes to the flow in Bitbucket v7.20. Depending on your Bitbucket version, the setup is slightly different. Please follow the instructions for the correct version of Bitbucket below:

Bitbucket v7.20 and above

  1. Click on Create link button. Screenshot of Bitbucket Application Links page.
  2. Make sure Atlassian product is selected (This will probably look confusing, but it is the only way to setup legacy OAuth app that Sourcegraph supports). Write Sourcegraph's external URL in the Application URL field and click Continue. Click Continue on the next screen again, even if Bitbucket Server / Bitbucket Data Center warns you about the given URL not responding. Screenshot of Bitbucket Create Link form.
  3. Write Sourcegraph as the Application Name and select Generic Application as the Application Type. Leave everything else unset and click Continue. Screenshot of second part of Bitbucket Create Link form.
  4. Now click the Edit button in the Sourcegraph Application Link that you just created and select the Incoming Authentication panel. Screenshot of first part of Bitbucket Edit Link form.
  5. Generate a Consumer Key in your terminal with echo sourcegraph$(openssl rand -hex 16). Copy this command's output and paste it in the Consumer Key field. Write Sourcegraph in the Consumer Name field. Screenshot of second part of Bitbucket Edit Link form.
  6. Generate an RSA key pair in your terminal with ssh-keygen -t rsa -b 4096 -o -a 100 -f sourcegraph.pem -m PEM && openssl rsa -in sourcegraph.pem -pubout > sourcegraph.pub. Note that the private key must be in PKCS#1 format. Copy the contents of sourcegraph.pub and paste them in the Public Key field. Screenshot of third part of Bitbucket Edit Link form.
  7. Scroll to the bottom and check the Allow 2-Legged OAuth checkbox, then write your admin account's username (this must match the username used in the external service configuration. In an instance where you may choose to use a service account, make sure that it has admin privileges.) in the Execute as field and, lastly, check the Allow user impersonation through 2-Legged OAuth checkbox. Press Save. Screenshot of last part of Bitbucket Edit Link form.
  8. Go to your Sourcegraph's Manage code hosts page (i.e. https://sourcegraph.example.com/site-admin/external-services) and either edit or create a new Bitbucket Server / Bitbucket Data Center connection. Add the following settings: 
    JSON
    {
  // Other config goes here
  "authorization": {
    "identityProvider": {
      "type": "username"
    },
    "oauth": {
      "consumerKey": "<KEY GOES HERE>",
      "signingKey": "<KEY GOES HERE>"
    }
  }
}
  9. Copy the Consumer Key you generated before to the oauth.consumerKey field and the output of the command base64 sourcegraph.pem | tr -d '\n' to the oauth.signingKey field. Finally, save the configuration. You're done!

Bitbucket v7.19 and below

  1. Write Sourcegraph's external URL in the text area (e.g. https://sourcegraph.example.com) and click Create new link.
  2. Click Continue even if Bitbucket Server / Bitbucket Data Center warns you about the given URL not responding.
  3. Write Sourcegraph as the Application Name and select Generic Application as the Application Type. Leave everything else unset and click Continue.
  4. Now click the edit button in the Sourcegraph Application Link that you just created and select the Incoming Authentication panel.
  5. Generate a Consumer Key in your terminal with echo sourcegraph$(openssl rand -hex 16). Copy this command's output and paste it in the Consumer Key field. Write Sourcegraph in the Consumer Name field.
  6. Generate an RSA key pair in your terminal with openssl genrsa -out sourcegraph.pem 4096 && openssl rsa -in sourcegraph.pem -pubout > sourcegraph.pub. Copy the contents of sourcegraph.pub and paste them in the Public Key field.
  7. Scroll to the bottom and check the Allow 2-Legged OAuth checkbox, then write your admin account's username in the Execute as field and, lastly, check the Allow user impersonation through 2-Legged OAuth checkbox. Press Save.
  8. Go to your Sourcegraph's Manage code hosts page (i.e. https://sourcegraph.example.com/site-admin/external-services) and either edit or create a new Bitbucket Server / Bitbucket Data Center connection. Add the following settings: 
    JSON
    {
  // Other config goes here
  "authorization": {
    "identityProvider": {
      "type": "username"
    },
    "oauth": {
      "consumerKey": "<KEY GOES HERE>",
      "signingKey": "<KEY GOES HERE>"
    }
  }
}
  9. Copy the Consumer Key you generated before to the oauth.consumerKey field and the output of the command base64 sourcegraph.pem | tr -d '\n' to the oauth.signingKey field. Finally, save the configuration. You're done!

Fast permission sync with Bitbucket Server plugin

By installing the Bitbucket Server plugin, you can make use of the fast permission sync feature that allows using Bitbucket Server / Bitbucket Data Center permissions on larger instances.

Fast permission syncing

With the Sourcegraph Bitbucket Server plugin you can enable fast permission syncing:

  1. Connect Bitbucket Server / Bitbucket Data Center to Sourcegraph (see instructions above).
  2. Follow the instructions to set up repository permissions with Bitbucket Server / Bitbucket Data Center.
  3. Install the Sourcegraph Bitbucket Server plugin on your Bitbucket Server / Bitbucket Data Center instance.
  4. In Sourcegraph, go to Site admin > Manage code hosts and edit the Bitbucket Server / Bitbucket Data Center configuration.
  5. Add the "plugin.permissions" property:
JSON
{
  // [...]
  "plugin": {
    "permissions": "enabled"
  }
}

Authentication for older Bitbucket Server / Bitbucket Data Center versions

Bitbucket Server / Bitbucket Data Center versions older than v5.5 require specifying a less secure username and password combination, as those versions of Bitbucket Server / Bitbucket Data Center do not support personal access tokens.

HTTPS cloning

Sourcegraph by default clones repositories from your Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center. You can exclude these repositories in search with archived:no search syntax.

Internal rate limits

See Internal rate limits.

Configuration

Bitbucket Server / Bitbucket Data Center 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_server.schema.json

JSON
{
	// If non-null, enforces Bitbucket Server / Bitbucket Data Center repository permissions.
	"authorization": null,
 
	// TLS certificate of the Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center 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://sourcegraph.com/docs/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 / Bitbucket Data Center instance.
	//
	// If "http", Sourcegraph will access Bitbucket Server / Bitbucket Data Center repositories using Git URLs of the form http(s)://bitbucket.example.com/scm/myproject/myrepo.git (using https: if the Bitbucket Server / Bitbucket Data Center instance uses HTTPS).
	//
	// If "ssh", Sourcegraph will access Bitbucket Server / Bitbucket Data Center repositories using Git URLs of the form ssh://git@example.bitbucket.org/myproject/myrepo.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"
 
	// Deprecated and ignored field which will be removed entirely in the next release. BitBucket repositories can no longer be enabled or disabled explicitly.
	"initialRepositoryEnablement": false,
 
	// The password to use when authenticating to the Bitbucket Server / Bitbucket Data Center instance. Also set the corresponding "username" field.
	//
	// For Bitbucket Server / Bitbucket Data Center instances that support personal access tokens (Bitbucket Server / Bitbucket Data Center version 5.5 and newer), it is recommended to provide a token instead (in the "token" field).
	"password": null,
 
	// Configuration for Bitbucket Server / Bitbucket Data Center Sourcegraph plugin
	"plugin": null,
 
	// An array of project key strings that defines a collection of repositories related to their associated project keys
	"projectKeys": 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 / Bitbucket Data Center repository.
	//
	//  - "{host}" is replaced with the Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center 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 / Bitbucket Data Center 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 / Bitbucket Data Center 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 / Bitbucket Data Center personal access token with Read permissions. When using batch changes, 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 / Bitbucket Data Center instances that don't support personal access tokens (Bitbucket Server / Bitbucket Data Center version 5.4 and older), specify user-password credentials in the "username" and "password" fields.
	"token": null,
 
	// URL of a Bitbucket Server / Bitbucket Data Center 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 / Bitbucket Data Center instance. Also set the corresponding "token" or "password" field.
	"username": null,
 
	// DEPRECATED: Switch to "plugin.webhooks"
	"webhooks": null
}

Configuration Notes

Bitbucket Server/Data Center connections provide comprehensive configuration options for enterprise environments:

  • Repository Selection: Use repos for specific repositories in projectKey/repositorySlug format, repositoryQuery for API-based filtering, and exclude for fine-grained exclusions
  • Project Keys: The projectKeys field allows syncing all repositories from specific projects
  • Personal Repository Handling: Use excludePersonalRepositories to filter out personal repositories that may be accessible
  • Path Patterns: The repositoryPathPattern field supports variables like {host}, {projectKey}, and {repositorySlug} for flexible repository naming

Authentication Methods

Bitbucket Server supports multiple authentication approaches:

  • Personal Access Tokens: Recommended for v5.5+ with granular permissions
  • Username/Password: Required for older versions (pre-5.5) that don't support PATs
  • OAuth1: For permission syncing with application links
  • OAuth2: Simplified permission syncing (requires auth provider configuration)

Rate Limiting Configuration

Bitbucket Server connections include rate limiting for API management:

  • Default: 28,800 requests per hour with rate limiting enabled
  • Adjust based on your instance's capacity and usage patterns
  • Monitor API usage to prevent hitting Bitbucket's internal limits

Security Considerations

Authentication Security

Personal Access Tokens: Provide fine-grained access control:

  • Create tokens with minimal required permissions (read for syncing, write for Batch Changes)
  • Use dedicated service accounts rather than personal tokens
  • Regularly rotate tokens and audit their usage
  • Tokens are preferred over username/password for better security

OAuth Configuration: Requires careful setup but provides enhanced security:

  • OAuth1 requires RSA key pairs and proper application link configuration
  • OAuth2 provides simpler setup with similar security benefits
  • Both methods support user impersonation for proper permission syncing

Permission Syncing Security

Bitbucket Server permission syncing has specific security requirements:

  • Username Matching: Requires identical usernames between Sourcegraph and Bitbucket Server
  • External Authentication: Use LDAP/Active Directory for consistent user management
  • Username Changes: Disable username changes (auth.enableUsernameChanges: false) to prevent privilege escalation
  • Plugin Benefits: The Sourcegraph plugin enables more efficient permission syncing and personal repository support

SSL/TLS Configuration

For Bitbucket Server instances with custom certificates:

  • Use the certificate field to specify custom CA certificates
  • Obtain certificates using: openssl s_client -connect HOST:443 -showcerts
  • Ensure certificate chain includes all intermediate certificates

When configuring OAuth1 application links:

  • Generate strong consumer keys using cryptographic randomness
  • Use RSA keys with at least 4096-bit length
  • Store private keys securely and restrict access
  • Enable 2-Legged OAuth with proper execute-as user configuration

Common Examples

Basic Repository Sync with Personal Access Token

JSON
{
  "url": "https://bitbucket.company.com",
  "username": "sourcegraph-service",
  "token": "NjY4MDAzNDI2NTMx...",
  "repos": [
    "PROJECT/repository-name",
    "SHARED/common-library"
  ]
}

Project-wide Sync with Exclusions

JSON
{
  "url": "https://bitbucket.company.com",
  "username": "sourcegraph-service", 
  "token": "NjY4MDAzNDI2NTMx...",
  "projectKeys": ["ENGINEERING", "PLATFORM"],
  "exclude": [
    {"name": "ENGINEERING/deprecated-service"},
    {"pattern": "^.*-archive$"}
  ],
  "excludePersonalRepositories": true
}

Advanced Query with OAuth2 Authorization

JSON
{
  "url": "https://bitbucket.company.com",
  "username": "sourcegraph-service",
  "token": "NjY4MDAzNDI2NTMx...",
  "repositoryQuery": [
    "?name=microservice&projectname=PLATFORM",
    "?visibility=public"
  ],
  "authorization": {
    "oauth2": true
  }
}

SSH Configuration with Custom Path Pattern

JSON
{
  "url": "https://bitbucket.company.com",
  "username": "sourcegraph-service",
  "token": "NjY4MDAzNDI2NTMx...",
  "repositoryQuery": ["?projectname=MOBILE"],
  "gitURLType": "ssh",
  "repositoryPathPattern": "bitbucket/{projectKey}/{repositorySlug}",
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}

Plugin-enabled Fast Permission Sync

JSON
{
  "url": "https://bitbucket.company.com", 
  "username": "sourcegraph-service",
  "token": "NjY4MDAzNDI2NTMx...",
  "repositoryQuery": ["all"],
  "authorization": {
    "oauth2": true
  },
  "plugin": {
    "permissions": "enabled"
  },
  "rateLimit": {
    "enabled": true,
    "requestsPerHour": 20000
  }
}

Best Practices

Authentication Management

  1. Use Personal Access Tokens whenever possible instead of username/password authentication
  2. Create dedicated service accounts for Sourcegraph rather than using personal accounts
  3. Implement token rotation policies to regularly refresh access tokens
  4. Configure OAuth2 for permission syncing when user authentication is required

Repository Organization

  1. Use project-based organization with projectKeys for better management at scale
  2. Implement exclusion patterns to filter out archived, personal, or test repositories
  3. Use consistent path patterns that reflect your organizational structure
  4. Exclude personal repositories unless specifically required for your use case

Performance Optimization

  1. Install the Sourcegraph plugin for faster permission syncing and enhanced features
  2. Configure appropriate rate limits based on your Bitbucket Server instance's capacity
  3. Use specific repository queries rather than broad "all" queries when possible
  4. Monitor API usage to avoid overloading your Bitbucket Server instance

Permission Management

  1. Ensure username consistency between Sourcegraph and Bitbucket Server through external auth
  2. Disable username changes in Sourcegraph site configuration to prevent privilege escalation
  3. Test permission syncing thoroughly before deploying to production
  4. Use the Sourcegraph plugin for more efficient permission syncing

Maintenance

  1. Monitor connection health through the site admin interface
  2. Keep certificates updated for Bitbucket Server instances with custom SSL
  3. Review repository queries periodically as your project structure evolves
  4. Update the Sourcegraph plugin when new versions become available