About
-
You use the Bitbucket integration to track changes in repositories stored at the bitbucket.org website.
-
Collaborator can work with repositories of both Git and Mercurial types.
-
When you integrate Collaborator with a Bitbucket 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. See below for details.
-
Do not confuse Bitbucket and Bitbucket Server (On-Premise) integration types. Bitbucket Server is a self-hosted version of Bitbucket. To integrate with it, use the Bitbucket Server (On-Premise) integration type.
Requirements
-
Your Collaborator server must be accessible to Bitbucket and vice versa. You may need to configure your firewall or enable tunneled connections to expose the server’s External URL to the Web. If needed, ask your system administrator for help.
-
To configure integration settings in Collaborator, you need Administrator privileges.
- Bitbucket will deprecate their API 1.0 starting from 29th of April 2019. You will need to upgrade to Collaborator version 11.5.11502 or later to use Bitbucket integration.
1. Get Bitbucket App Password
To integrate Collaborator with Bitbucket, you need an app password that will be used to access your repository. For detailed information on generating app passwords, follow instructions on this page of Bitbucket documentation:
Notes:
-
When creating an app password, make sure to enable the following permissions:
-
In the Repositories category:
- Read
- Write
- Admin
-
In the Pull requests category:
- Read
- Write
-
In the Webhook category:
- Read and write
-
-
After Bitbucket generates the app password, it will display it on screen. Save the app password somewhere or write it down. You will need it later, when you will configure the integration between Collaborator and Bitbucket.
2. 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. |
| 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. |
Easy Add Repository tab (recommended)
-
Log in to Collaborator as administrator. (To integrate with Bitbucket repositories, you need administrator privileges in Collaborator).
-
On the Collaborator main toolbar, click ADMIN, and then select Remote System Integration from the tree on the left. Then switch to the Easy Add Repository tab.
-
On the tab, select Bitbucket in the Add repository for box and click Next:
Click the image to enlarge it.
-
Collaborator will displays a page with connection details.
Fill in the edit boxes:
Click the image to enlarge it.
Setting Description Username
Required. A name of user account to use for authentication.
For single-user repositories (https://bitbucket.org/UserName/RepoName), this should be the user account name (UserName).
For team owned repositories (https://bitbucket.org/TeamName/RepoName), this should be the name of user account who belongs to the desired team.
App password
Required. The app password for a Bitbucket account that has access to the remote repository.
This is the password that we generated in Bitbucket earlier.
Team name
Required only for team owned repositories (https://bitbucket.org/TeamName/RepoName). Specifies the name of your Bitbucket team account (TeamName).
User role
Optional. Defines which types of repositories to track:
Value Description Owner (default) Repositories that are owned by the specified user. Admin Repositories to which the user has administrator access. Member Repositories to which the user has read access. Contributor Repositories to which the user has write access. Webhooks will be created for those repositories where allowed by the repository permissions for the specified user.
Override existing configurations
Optional. Specifies whether to override existing configurations that track the same repository URI.
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.If this field is empty, main branch of the repository will be tracked (master for Git repos and default for Mercurial repos).
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.When review completed
Optional. Specifies an action to perform when a review corresponding to a pull request was accomplished:
Value Description Do nothing Do not perform any action. Merge pull request Merge pull request that matches the review. Merge pull request and delete its branch Merge pull request that matches the review and delete the corresponding branch. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. When review cancelled/deleted/rejected
Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:
Value Description Do nothing Do not perform any action. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. 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
-
After you specified the settings, click Load repositories. This will display a list of repositories available for the specified user account or organization in Bitbucket. Select the repositories to track and click Create for selected.
Alternatively, you can click Create for all and use the settings for all repositories that are available for the specified user account or organization in Bitbucket. Collaborator will create an individual configuration for each repository, and, if needed, will create a webhook for each repo in Bitbucket.
Configure Remote Systems tab
-
Log in to Collaborator as an administrator. (To configure integration settings, you need administrator privileges in Collaborator).
-
On the Collaborator main toolbar, click ADMIN, and then select Remote System Integration from the tree on the left. Then switch to the Configure Remote Systems tab.
-
In the New Remote System Configuration section, select Bitbucket and click Create:
Click the image to enlarge it.
-
Collaborator will display a page with configuration settings. Specify the setting values:
Setting Description Title
Required. The configuration name as it will be displayed in Collaborator user interface.
Bitbucket repo URI
Required. The URI of the Bitbucket repository to be tracked, for example,
https://[email protected]/johnsmith/repo.git.You can copy the URI from the repository settings in Bitbucket:
Click the image to enlarge it.
App password
Required. The app password of the Bitbucket account that has access to the repository.
This is the password that we generated in Bitbucket earlier.
Username for authentication
Optional. Required for team repositories. Specifies an account name to use for authentication in Team repositories. For single-user repositories, account name is taken from the repo URI.
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.If this field is empty, main branch of the repository will be tracked (master for repos of the Git type and default for repos of the Mercurial type).
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.When review completed
Optional. Specifies an action to perform when a review corresponding to a pull request was accomplished:
Value Description Do nothing Do not perform any action. Merge pull request Merge pull request that matches the review. Merge pull request and delete its branch Merge pull request that matches the review and delete the corresponding branch. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. When Review cancelled/deleted/rejected
Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:
Value Description Do nothing Do not perform any action. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. Reopen a review when
Optional. Specifies if integration should reopen completed review when the respective pull request was updated.
Webhook status
Indicates the current status of the webhook:
Status Description 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.To learn more about webhook settings on the Bitbucket side, see Bitbucket documentation:
https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html -
Click Test Connection to verify if you entered data correctly.
Click Save to store the settings.
3. Enable Configuration
After you finished configuring integration settings, you need to enable the integration:
- In Collaborator, go to ADMIN > Remote System Integration.
- Switch to the Integration Status tab. Here you can enable or disable integrations quickly.
- Find the Enable Bitbucket Integration setting and change it to Yes.
Click the image to enlarge it.
Now the integration between Collaborator and Bitbucket is configured and running.
4. Link Collaborator User Account to Bitbucket Account
The last step is to link Collaborator user accounts to the Bitbucket accounts. See —
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.
-
To create reviews on pull requests for forked repositories, the following conditions should met:
-
Forked repository of the same repository owner can be public or private.
-
Forked repository of a different repository owner must be public repository.
-
-
To avoid creating reviews for merge commits, keep their messages default or start them with the Merged in substring.
-
Right after you set up integration with some Bitbucket repo, Collaborator will not track the very first push or pull request to this repo. Subsequent requests will be tracked as they should be tracked.
-
The first push or pull request to a newly created branch will be tracked only if that branch was started from the master branch. As a workaround, create new branches without commits — the subsequent push events will be tracked as they should be.
See Also
Bitbucket Server (On-Premise) Integration
Source Control Integrations