Integrate with Bitbucket

You can integrate a project in YouTrack with VCS repositories that are hosted on bitbucket.org. A Bitbucket integration 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 is either the owner of the repository or has admin-level access to the repository. This is the user account whose login and password are used for authentication. If you use an account that does not have admin-level access to the repository, you encounter an unable to perform operation error.
You are able to access the Bitbucket server with an email address and password. The YouTrack integration with Bitbucket does not support two-step verification.

Configure the Bitbucket Integration

The first step is to establish a connection between a project and YouTrack and a repository in Bitbucket. To connect with Bitbucket, you need to log in with a username and password. This authentication grants YouTrack access to the repository based on the access that is granted to your Bitbucket account.

To connect to a Bitbucket repository:

Click the Projects link in the header to open the Projects list.
From the Administration menu for your project, select VCS.
Click the New VCS Integration button.
- The New VCS Integration dialog opens.
For the Server type, select Bitbucket.
Paste the URL that points to your Bitbucket repository into the Repository URL input field.
Enter the login and password for the Bitbucket account.
Click the Save button.
- Your YouTrack project is integrated with the selected repository in Bitbucket.
- Commits from the Bitbucket 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.

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
YouTrack project	Sets the project in which the VCS integration is active. You can switch the integration to update issues in another project without having to add a new integration.
Committers	Restricts processing to commits by members of the specified group. When set to a specific group, commits by users who are not members are not processed by the integration.
Monitored branches	Stores the names of the branches that you want to monitor for changes. 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: `+:refs/heads/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, YouTrack detects and generates issue comments from commit messages. Otherwise, the entire commit message is displayed with the VCS change in the issue activity stream. We recommend that you 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.

Troubleshooting

Condition — References to issues in VCS commits are not shown as VCS changes in YouTrack. Commands that are specified in VCS commits are not applied to issues in YouTrack.

Cause	Solution
The users who commit changes to the repository are not members of the Committers group in the integration settings.	Either add the committers to the specified group in YouTrack or modify the selection in the integration settings.
The users who commit changes to the repository do not have permission to update issues in the connected project.	Either add these users to the project team or grant them a role in the project that includes the Read Issue and Update Issue permissions.
The webhooks in the integrated VCS don't exist, are disabled, or are otherwise malformed.	Check the webhooks in the settings for your VCS repository. Make sure that the webhooks exist and that they are enabled. If you suspect that there is a problem with a webhook, delete or disable it in the settings for your VCS and set up a new VCS integration in YouTrack.

Cause

Solution

The users who commit changes to the repository are not members of the Committers group in the integration settings.

Either add the committers to the specified group in YouTrack or modify the selection in the integration settings.

The users who commit changes to the repository do not have permission to update issues in the connected project.

Either add these users to the project team or grant them a role in the project that includes the Read Issue and Update Issue permissions.

The webhooks in the integrated VCS don't exist, are disabled, or are otherwise malformed.

Check the webhooks in the settings for your VCS repository. Make sure that the webhooks exist and that they are enabled.

If you suspect that there is a problem with a webhook, delete or disable it in the settings for your VCS and set up a new VCS integration in YouTrack.

Condition — YouTrack returns the error unable to perform operation when you try to establish a connection with a Bitbucket repository. Follow the instructions below to resolve the problem.

Cause	Solution
The login and password that are used for authentication with Bitbucket belong to a user who is not the owner of the repository and does not have admin-level access. This integration uses webhooks, which can only be created by the owner of the repository and other users who are granted admin access.	Access the User and group access settings for your repository and grant admin access to the user you are using to authenticate with Bitbucket. You can also grant admin access to a group where this user is a member. Alternatively, use the login and password of an account that is already granted admin access in the repository.

Cause

Solution

The login and password that are used for authentication with Bitbucket belong to a user who is not the owner of the repository and does not have admin-level access. This integration uses webhooks, which can only be created by the owner of the repository and other users who are granted admin access.

Access the User and group access settings for your repository and grant admin access to the user you are using to authenticate with Bitbucket. You can also grant admin access to a group where this user is a member.

Alternatively, use the login and password of an account that is already granted admin access in the repository.

Last modified: 8 March 2019

YouTrack Standalone 2018.4 Help