Bitbucket Server (On-Premise) Integration

Applies to Collaborator 14.5, last modified on April 18, 2024

About

  • You use the Bitbucket Server (On-Premise) integration to track changes in repositories stored at your Bitbucket Server.

    Collaborator can work with repositories of both Git and Mercurial types.

    Collaborator's Bitbucket integration will no longer be able to support Mercurial starting on June 1, 2020, when Atlassian will officially remove Mercurial features and repositories from Bitbucket and its API.

    Bitbucket Server and Bitbucket Data Center version 5.4 or later is supported.

  • When you integrate Collaborator with some Bitbucket Server repository, your Collaborator server creates reviews automatically for pull requests in that repo, as well as for push events that occur in that repo. For complete information on what the integration means and how you can benefit from it, see Integration With Repository Hosting Services.

  • To inform Collaborator about changes, Bitbucket Server uses a webhook that sends notification messages to your Collaborator server.

  • To set up the webhook and other integration parameters, you need to set up some options in Collaborator and in Bitbucket Server. See below for details.

  • Do not confuse Bitbucket Server (On-Premise) and Bitbucket integration types. Use the Bitbucket Server type to track changes in repositories stored on your Bitbucket Server. To integrate with repositories stored at the bitbucket.com website, use the Bitbucket integration type.

Requirements

  • Your Collaborator server must be accessible to your Bitbucket server and vice versa. You may need to configure your firewall or enable tunneled connections to expose the server’s External URL to your Bitbucket server. If needed, ask your system administrator for help.

  • Note that Collaborator makes API calls to https://api.github.com which is a machine separate from https://github.com. When using trusted connections, ensure that the security certificates from both machines are accepted.

  • To configure integration settings in Collaborator, you need Administrator privileges.

  • Also, you need to know the user name and password of the administrator user on your Bitbucket server.

1. Set up integration

Collaborator offers two groups of settings for configuring integration with remote repositories:

Settings When to use
Easy Add Repository tab We recommend using these settings to set up new connections to your repositories quickly.
Configure Remote Systems tab Use these settings to configure existing connections. Though you can use these settings to set up integration, the settings on the “Easy Add Repository” tab will help you do this faster.

Additionally, you can create auto-polling configuration to periodically look for new repositories on the specified server and suggest creating integrations for them.

Easy Add Repository tab (recommended)

  1. Log in to Collaborator as administrator. (To integrate with Bitbucket server, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Easy Add Repository tab.

  3. On the tab, select Bitbucket Server (On-Premise) in the Add repository for box and click Next:

    Integration with Bitbucket Server: Start

    Click the image to enlarge it.

  4. Collaborator will displays a page with connection details.

    Integration with Bitbucket Server: Settings

    Click the image to enlarge it.

    Specify settings in the the following sections of the wizard:

    Connection settings
    Setting Description

    Host name

    Required. Denotes the host name of your Bitbucket Server.

    Admin username

    Required. The user name of the Bitbucket Server administrator.

    Admin password

    Required. The password of the Bitbucket Server administrator.

    After specifying connection settings, you can click Load repositories to retrieve a list of repositories available for the specified user or team.

    Select repositories

    Select repositories

    Optional. Displays a list of repositories available for the specified user or team.

    Select which repositories you need to track. Use Ctrl+click or Shift+click for multi-selection.

    If any of the repositories were chosen, the wizard will display the Create for selected button below the settings section.

    If none of the repositories were chosen, the wizard will display the Create for all button below the settings section.

    Override existing configurations

    Optional. Specifies whether to override existing configurations that track the same repository URI.
    Branches

    Branches to track

    Optional. The names of branches to track changes and create reviews on pull requests and direct pushes. Separate multiple branch names with commas.

    You can use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches. Note that wildcards and regular expressions cannot be used if you enable the Status check required setting (see below).

    If this field is empty, main branch in the repository will be tracked (main for Git repositories and default for Mercurial repositories).

    Ignore pushes for branches

    Optional. Specifies branches for which Collaborator will not create reviews on direct pushes.

    You can enter one or several branch names. Separate multiple branch names with commas. You can also use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches.
    Pull request actions

    Create review automatically

    If enabled, reviews for pull request are created automatically.

    If disabled, user can add pull request to a review manually through Remote System links, by API call or by special command directly from pull request.

    When review completed

    Optional. Specifies an action to perform when a review corresponding to the pull request was accomplished:

    • Do nothing: Do not perform any action.
    • Merge pull request: Merge pull request that corresponds to a review.
    • Merge pull request and close its branch: Merge pull request that corresponds to a review and then close the respective branch.

    The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, pull request will be merged according to project settings on the Bitbucket Server side (Project settings > Merge strategies). To learn more about pull request merge strategies, see Bitbucket Server documentation.

    Allow users to select merge strategy in review

    If enabled, regular users would be able to choose pull request merge strategies in each separate review.

    If disabled, all pull requests would behave as specified by the When review completed setting.

    Wait for signature (if enabled) before merge

    Optional. Effective, if any of merge actions (merge or squash) was selected in When review completed setting.

    If enabled Collaborator will wait for the completed review to be signed off before merging the respective pull request. Otherwise, pull request will be merged immediately, even if the review have not been signed yet.

    Allow to complete review with conflicts in pull request

    Should it be possible to complete a review if there are conflicts in the respective pull request.

    When review cancelled/deleted/rejected

    Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:

    • Do nothing: Do not perform any action.
    • Decline pull request: Decline pull request that corresponds to a review.

    Auto assign reviewers

    Whether to assign Collaborator reviewers when some specific users or teams were added as pull request reviewers or specified as code owners on the Bitbucket server side and integration can match those Bitbucket server users with Collaborator users.

    Reopen a review when

    Optional. Specifies in what cases Collaborator should reopen completed reviews. May include any combination of the following:

    • when a push to a pull request is made,
    • when a comment is added to a pull request,
    • when a comment is added to commit which is a part of a pull request
    Review settings

    Default review template

    Optional. Specifies the initial template that will be chosen when creating review (if set to "None", the first template in the list will be chosen).

    The value of this setting overrides the value of Default review template setting specified on group level.

  5. Click the Create for selected button or the Create for all button to create repository integrations and automatically create webhooks for each repository in Bitbucket Server. To stop suggesting integrations for some specific repositories, select these repositories in the list and click Ignore selected.

    For every repository a separate configuration will be created in Collaborator and a webhook will be automatically added in Bitbucket Server.

Configure Remote Systems tab

  1. Log in to Collaborator as an administrator. (To configure integration settings, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Configure Remote Systems tab.

  3. In the New Remote System Configuration section, select Bitbucket Server (On-Premise) and click Create:

    Integration with Bitbucket Server: Start

    Click the image to enlarge it.

  4. Collaborator will display a page with configuration settings. Specify settings in the following sections:

    Bitbucket Server settings
    Setting Description

    Title

    Required. The configuration name as it will be displayed in Collaborator user interface.

    Bitbucket repo URI

    Required. The URI of the desired repository on your Bitbucket Server, for example, http://hostname/projects/PROJ/repos/my_repo.

    You should copy the repository URI from the browser’s address bar, rather than from the repository’s clone URI.

    Both Mercurial and Git repositories are supported.

    Admin username

    Required. The user name of the Bitbucket Server administrator.

    Admin password

    Required. The password of the Bitbucket Server administrator.

    Webhook status

    Indicates the current status of the webhook:

    • Webhook is absent: The webhook has not been created yet.
    • Webhook isn't active: The webhook has been created, but is inactive.
    • Up and running: The webhook is active.

    To create or activate a webhook, click Update webhook.

    Important: Click this button, when you set up integration with your repository for the first time.
    Branches

    Branches to track

    Optional. The names of branches to track changes and create reviews on pull requests and direct pushes. Separate multiple branch names with commas.

    You can use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches. Note that wildcards and regular expressions cannot be used if you enable the Status check required setting (see below).

    If this field is empty, main branch in the repository will be tracked (main for Git repositories and default for Mercurial repositories).

    Ignore pushes for branches

    Optional. Specifies branches for which Collaborator will not create reviews on direct pushes.

    You can enter one or several branch names. Separate multiple branch names with commas. You can also use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches.
    Pull request actions

    Create review automatically

    If enabled, reviews for pull request are created automatically.

    If disabled, user can add pull request to a review manually through Remote System links, by API call or by special command directly from pull request.

    When review completed

    Optional. Specifies an action to perform when a review corresponding to the pull request was accomplished:

    • Do nothing: Do not perform any action.
    • Merge pull request: Merge pull request that corresponds to a review.
    • Merge pull request and close its branch: Merge pull request that corresponds to a review and then close the respective branch.

    The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, pull request will be merged according to project settings on the Bitbucket Server side (Project settings > Merge strategies). To learn more about pull request merge strategies, see Bitbucket Server documentation.

    Allow users to select merge strategy in review

    If enabled, regular users would be able to choose pull request merge strategies in each separate review.

    If disabled, all pull requests would behave as specified by the When review completed setting.

    Wait for signature (if enabled) before merge

    Optional. Effective, if any of merge actions (merge or squash) was selected in When review completed setting.

    If enabled Collaborator will wait for the completed review to be signed off before merging the respective pull request. Otherwise, pull request will be merged immediately, even if the review have not been signed yet.

    Allow to complete review with conflicts in pull request

    Should it be possible to complete a review if there are conflicts in the respective pull request.

    When review cancelled/deleted/rejected

    Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:

    • Do nothing: Do not perform any action.
    • Decline pull request: Decline pull request that corresponds to a review.

    Auto assign reviewers

    Whether to assign Collaborator reviewers when some specific users or teams were added as pull request reviewers or specified as code owners on the Bitbucket server side and integration can match those Bitbucket server users with Collaborator users.

    Reopen a review when

    Optional. Specifies in what cases Collaborator should reopen completed reviews. May include any combination of the following:

    • when a push to a pull request is made,
    • when a comment is added to a pull request,
    • when a comment is added to commit which is a part of a pull request
    Review settings

    Default review template

    Optional. Specifies the initial template that will be chosen when creating review (if set to "None", the first template in the list will be chosen).

    The value of this setting overrides the value of Default review template setting specified on group level.

  5. Click Test Connection to verify if you entered data correctly.

    Click Save to store the settings.

    Click on Update Webhook button to add webhook for the repository on the remote system's side.

Creating Bitbucket auto-polling configuration

Sections above describe how to add integrations for existing repositories. When some new repositories are created on a server, you may integrate them manually. Alternatively, you can setup Bitbucket auto-polling configuration that will periodically look for new repositories on the specified server, user, workspace or project and suggest creating integrations for them.

  1. Log in to Collaborator as administrator. (To integrate with Bitbucket repositories, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Repository Auto-Polling tab.

  3. On the tab, select Bitbucket in the Add configuration box and click Next.

  4. Collaborator will displays a page with connection details.

    Integration with Bitbucket: Auto-polling Settings

    Click the image to enlarge it.

    Fill in the edit boxes:

    Setting Description
    Server URI Required. The URI of Bitbucket server, user, workspace or project to be polled for new repositories.

    Admin password

    Required. The password for the Bitbucket account to be tracked.

    Admin username

    Required. Specifies the user account name to be tracked.

    After specifying these values, you can click Test connection to verify if you entered data correctly.

  5. After you specified the values, click Save. This will create an auto-polling configuration and display it in the Auto-Polling Configurations List.
  6. Scroll down the Repository Auto-Polling tab and check that the Enable Auto-Polling setting is on and optionally change the Auto-Polling Interval setting.

Now Collaborator will automatically check if any new repositories were found on the specified server. Once found, it will notify administrators and suggest creating integrations with these newly created repositories via the Easy Add Repository wizard.

2. Link Collaborator user account to a Bitbucket Server account

The last step is to link Collaborator user accounts to the Bitbucket accounts. See —

Link User Accounts

Known Issues and Specifics

  • You can specify Bitbucket users as reviewers when you are creating a pull request. If your teammates link their Bitbucket accounts with their Collaborator accounts correctly, then Collaborator will automatically add those users as reviewers to the created review on the Collaborator side.

  • Due to certain limitations on the Bitbucket Server side, Collaborator is unable to create reviews, if paths of submitted files contain the percent symbol (%).

  • Collaborator will not create reviews on merge commits of pull requests when their merge commit message starts with the Merged in substring or when merge commit message was specified in the Pull Request Merge Info section.

  • The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, pull request will be merged according to project settings on the Bitbucket Server side (Project settings > Merge strategies). To learn more about pull request merge strategies, see Bitbucket Server documentation.

  • If the remote repository server is not accessible, Collaborator will retry connecting after a certain time period and will perform several retry attempts. Wait time is increased with each attempt: wait_time*1, wait_time*2, wait_time*3 and so on. Default wait time is 1 second and Collaborator will perform 3 retries. Wait time and maximal number of attempts could be configured via Java VM Options. If the server did not respond after all attempts, Collaborator will mark the respective webhook as inactive and put an exception to the remoteSystem.log

  • In order to create reviews on pull requests from forked repositories, the following conditions must comply:

    • Forked repository of the same repository owner can be public or private.
    • Forked repository of a different repository owner must be public repository.

See Also

Source Control Integrations
Bitbucket Integration

Highlight search results