Bitbucket Server Integration

You can integrate a project in YouTrack with VCS repositories on a self-hosted Bitbucket Server.

Integration with Bitbucket Server enables the following features in YouTrack:

Apply commands to YouTrack issues right from a commit comment or a pull request description. For more information, see Apply Commands in VCS Commits.
Track commits that are related to specific issues in the activity stream for each issue. For more information, see View and Edit VCS Changes.
Add links to YouTrack issues in commit messages. For more information, see Link Issues in VCS Commits.

Prerequisites

YouTrack is accessible to inbound connections. Specifically, you need to make sure that your network doesn't block connections between your VCS server and YouTrack.
The account that you use to connect to Bitbucket Server has admin-level access to the repository. This is the user account whose personal access token is used for authentication. If you use an account that does not have admin-level access to the repository, you encounter an You are not permitted to access this resource error.

Generate an Access Token in Bitbucket Server

The first thing you should do is generate an access token in Bitbucket Server. This token grants YouTrack access to the repository based on the access that is granted to your Bitbucket Server account.

To generate token in Bitbucket Server:

Log into Bitbucket Server, and click your avatar to open the user menu, then select Manage account item.
When the account settings page opens, in the sidebar select Personal access tokens.
In the Personal access tokens page, click the Create a token button.
In the Create a personal access token dialog, type in a name for the new token, and set permissions for it: "Read" for Projects, and "Admin" for Repositories. Then, click Create.
When the new token is generated, copy it - you will need it to configure the integration in YouTrack.

Configure the Bitbucket Server Integration

To connect with Bitbucket Server, you need to enter the personal access token for your Bitbucket Server account. This authentication grants YouTrack access to the repository based on the access that is granted to your account in Bitbucket Server.

To connect to a Bitbucket Server repository:

In the administration menu, select VCS Integrations.
Click the New VCS Integration button.
- The New VCS Integration dialog opens.
From the Main YouTrack project list, select the name of the primary project that you want to integrate with the VCS repository. You can add integrations with additional YouTrack projects after you have set up the connection to the repository.
For the Server type, select Bitbucket Server.
Paste the URL that points to your Bitbucket Server repository into the Repository URL input field.

YouTrack does not support URLs that end with .git. The URL for the repository should be provided in the following format:
<BitBucket_baseURL>/projects/<project-id>/repos/<repo_name>
For example:
https://bitbucket.example.com/projects/TPO/repos/test-project-src
Enter the generated Personal access token.
Click the Save button.
- Your YouTrack project is integrated with the selected repository in Bitbucket Server.
- Commits from the Bitbucket Server repository that reference an issue in the project are displayed in the activity stream of the referenced issue.
- The sidebar displays additional settings for configuring the VCS integration.
To learn more about these settings, see Integration Settings.

Advanced Server Settings

If you are unable to establish a connection to your repository using the basic settings on the New VCS Integration dialog, click the Show advanced server settings link.

Advanced settings for a VCS integration with Bitbucket Server.

You only need to enter values for these settings when you haven't set up a VCS integration with the target server. If you already have a working integration with a single repository on the server, you can add integrations with other repositories without setting these parameters again.

Use the following guidelines to set the values for these settings:

Setting	Description
URL	This setting helps to identify the path to the Bitbucket Server repository. If the repositories for your Bitbucket Server are available under `https://host[:port]/SOME_CONTEXT_PATH`, YouTrack is unable to determine where this context path ends and the actual path to the repository begins. To resolve this problem, enter the base URL for your Bitbucket Server. For example: `https://host:port/context_path`
SSL keys	If your server environment is set up to require HTTPS authentication, select the keystore that contains the private key for your YouTrack server. This key identifies your YouTrack server when it tries to establish a connection with Bitbucket Server. This setting is only used to support HTTPS authentication as required by connections to your internal network. The list only displays SSL keys that are already imported into YouTrack. To learn how to generate keystores files and upload them to YouTrack, see SSL Keys.

Setting

Description

URL

This setting helps to identify the path to the Bitbucket Server repository. If the repositories for your Bitbucket Server are available under https://host[:port]/SOME_CONTEXT_PATH, YouTrack is unable to determine where this context path ends and the actual path to the repository begins.

To resolve this problem, enter the base URL for your Bitbucket Server. For example: https://host:port/context_path

SSL keys

If your server environment is set up to require HTTPS authentication, select the keystore that contains the private key for your YouTrack server. This key identifies your YouTrack server when it tries to establish a connection with Bitbucket Server. This setting is only used to support HTTPS authentication as required by connections to your internal network.

The list only displays SSL keys that are already imported into YouTrack. To learn how to generate keystores files and upload them to YouTrack, see SSL Keys.

Integration Settings

By default, the VCS integration processes changes that are committed to the repository by any user in any branch. Any user who has access to the issue in YouTrack can view these changes in the issue activity stream.

If you only want to process changes by specific users in designated branches or restrict the visibility of VCS changes in YouTrack, you can customize the integration settings. Use following settings to customize the integration:

Setting	Description
Main YouTrack project	Sets the primary project in which the VCS integration is active.
Additional projects	Integrates the linked repository with one or more additional projects.
Repository	Displays the path to the repository in the integrated version control system. If needed, you can edit the location of the repository after you have set up the integration. For instructions, seeEdit Repository Settings.
Committers	Restricts the ability to update issues with commands in commit messages to members of the specified group. VCS changes from users who are not members of the selected group are still attached to related issues, but any commands that are specified in their commits are ignored.
Monitored branches	Stores the names of the branches that you want to monitor for changes. For Bitbucket integrations, use the short name instead of the fully qualified name of the branch. Use `+` to include a branch. Use `-` exclude a branch. Use `` as a wildcard. This placeholder matches one or more characters in a string. For example, to include all feature branches, use: +:feature/ To monitor all branches, leave the input field empty. If the address that you entered as the Repository URL when you connected to Bitbucket points to a specific branch, this branch is automatically added to the list of monitored branches when you set up the connection.
Parse commits for issue comments	When enabled, specific segments of commit message text are copied to issues as comments. When you copy parts of the commit message to the issue as comments, you can trigger @mention notifications and expose information to users who don't have access to VCS changes. This setting does not affect how commit messages are shown in VCS changes. The entire commit message, including commands and issue comments, is always shown as part of the VCS change record in the activity stream. You should only enable this option when: You want to mention other users in your commit messages and generate notifications when the text is copied to an issue comment. You restrict the visibility for VCS changes and want to make commit-related information visible to external users as comments. To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.
VCS changes visibility	Restricts the visibility of VCS changes to one or more groups of users in YouTrack. When unrestricted, the list of VCS changes is visible to any user who has permission to read issues in the project.

Last modified: 1 July 2020