Skip to content

Latest commit

 

History

History
145 lines (88 loc) · 9.63 KB

bitbucket_server.md

File metadata and controls

145 lines (88 loc) · 9.63 KB

Bitbucket Server / Bitbucket Data Center

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.

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

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.

Write Sourcegraph's external URL in the text area (e.g. https://sourcegraph.example.com) and click Create new link. Click Continue even if Bitbucket Server / Bitbucket Data Center warns you about the given URL not responding.

Write Sourcegraph as the Application Name and select Generic Application as the Application Type. Leave everything else unset and click Continue.

Now click the edit button in the Sourcegraph Application Link that you just created and select the Incoming Authentication panel.

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.

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.

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.

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:

{
	// Other config goes here
	"authorization": {
		"identityProvider": {
			"type": "username"
		},
		"oauth": {
			"consumerKey": "<KEY GOES HERE>",
			"signingKey": "<KEY GOES HERE>"
		}
	}
}

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:
{
  // [...]
  "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.

[View page on docs.sourcegraph.com](https://docs.sourcegraph.com/admin/external_service/bitbucket_server) to see rendered content.