# Bitbucket Integration

You can integrate a project in YouTrack with VCS repositories that are hosted on [bitbucket.org](https://bitbucket.org/).

> **Warning: Availability**
> The integration between YouTrack and Bitbucket is only supported in YouTrack versions 2019.1.51078 and later. Older versions of YouTrack use a version of the Bitbucket Cloud REST API that has been discontinued.

A Bitbucket integration enables the following features in YouTrack:

* Apply commands to YouTrack issues in commit messages. For more information, see [Apply Commands in VCS Commits](apply-commands-in-vcs-commits.html).

* Track commits that are related to specific issues in the activity stream for each issue. For more information, see [Commits](vcs-changes.html#view-edit-vcs-commits).

* Display the status of pull (merge) requests directly in the activity stream of any issue that is referenced in the title or description of the pull request. For details, see [Pull Requests](vcs-changes.html#pull-requests).

* Add links to YouTrack issues in commit messages or branch names. For more information, see [Link Issues in VCS Commits](map-issues-to-vcs-change-commit.html).

> **Note:**
> When you set up an integration with Bitbucket, you map a YouTrack project to a Bitbucket repository. This operation can also be performed by a project administrator on a per-project basis. For more information, see [Integrate with Bitbucket](integrate-project-with-bitbucket.html).
>
>
>
> As an administrator, you can enable the Bitbucket integration for any project in YouTrack.

## 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 Bitbucket email address and API token 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.

## 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 enter the credentials for your Bitbucket account. This authentication grants YouTrack access to the repository based on the access that is granted to your account in Bitbucket.

Procedure: To connect to a Bitbucket repository:

> **Tip:**
> Requires permissions: Update Project

1. From the main navigation menu in YouTrack, select ![](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/settings.svg) `Administration > Integrations > VCS Integration`.

2. Click the New VCS Integration button.

* The New VCS Integration dialog opens. ![New VCS Integration dialog with Bitbucket selected as the server type.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/new-bitbucket-vcs-integration.png)

3. 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.

4. For the Server type, select Bitbucket.

5. Paste the URL that points to your Bitbucket repository into the Repository URL input field.

6. For the Email, enter your email address for the Bitbucket account.

7. For the Access token, enter an API token for your Bitbucket account.

To create an API token, click the Create a token link to access your account in Bitbucket. Your API token for this integration requires the following permissions (scopes):

| Category | Permission |
| --- | --- |
| Repositories | Admin, Read |
| Pull requests | Read |
| Issues | Read |
| Webhooks | Read, Write |

8. 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. ![Bitbucket integration settings with repository and authentication fields.](https://resources.jetbrains.com.cn/help/img/youtrack/2026.2/bitbucket-integration-settings.png)

To learn more about these settings, see [Integration Settings](#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 the following settings to customize the integration:

| Setting | Description |
| --- | --- |
| 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, see [Edit Repository Settings](edit-repository-settings.html).    |
| 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. |
| 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. |
| Processing scheme for VCS changes | Choose how to process VCS changes when the commit message references an issue ID. The following options are supported:       * Add commits, ignore commands: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Any command in the commit message is ignored.    * Add commits in all projects, apply commands in main: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Only apply commands to issues that belong to the currently selected main project. > **Note:** > When this option is selected, the Parse commits for issue comments option becomes available.    * Add commits and apply commands to all projects: Add VCS changes to issues when a commit message references an ID that belongs to an issue in an integrated project. Update issues in any integrated project when commit messages include commands. > **Note:** > * Scheme is available only when at least one Additional project is specified in the integration settings. > > * When this option is selected, the Parse commits for issue comments option becomes available.    |
| Monitored branches | Stores the names of the branches that you want to monitor for changes.       * Use `+` to include a branch.    * Use `-` to exclude a branch.    * For the `branch name`, use the fully qualified name of the branch. For example, `refs/heads/<branch name>`.    * Use `*` as a wildcard. This placeholder matches one or more characters in a string. For example, to include all feature branches, use: ```SHELL +:refs/heads/feature/* ``` You can only use one wildcard character per branch pattern. If you specify a pattern that contains more than one asterisk character, only the first is evaluated as a wildcard.    * To monitor all branches, leave the input field empty.     If the address that you entered as the Repository URL when you connected to the repository 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 |    > **Note:** > This option is shown in the UI only when either of the following processing schemes is selected: > > > > * Add commits in all projects, apply commands in main > > * Add commits and apply commands to all projects     When enabled, specific lines of text in commit messages 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](apply-commands-in-vcs-commits.html).   |
| Check branch names for issue references | When enabled, the integration checks for references to issues in branch names for commits. This option was added for teams that use a branch-per-ticket process, so their developers don't have to mention issue IDs in their commit messages explicitly. |
| 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 the issue. |

## Available Actions

When you select an integrated version control system in the list, the following actions are available in the toolbar:

| Action | Description |
| --- | --- |
| Disable | Shuts off the connection between the integrated project and the VCS repository. The configuration is not changed and can be enabled at any time. |
| Edit | Opens the integration settings dialog in the sidebar for the selected project and repository. |
| Delete | Removes the settings for the integrated project from YouTrack.     This action also removes all VCS changes that were added to issues for commits in the linked repository.     While the action itself cannot be undone, you can use the Import action to restore VCS changes that were removed accidentally.   |
| Import commits and open pull requests | Checks the commit history in the linked repository and adds VCS changes to issues that are referenced in commit messages. This option is only available for integrations that are currently enabled.     You can use this action to restore VCS changes that were removed when an integration was accidentally deleted or to migrate links to issues in a new project.   |

## Troubleshooting

Condition — References to issues in VCS commits are not shown as VCS changes in YouTrack.

| Cause | Solution |
| --- | --- |
| 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 — 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. |
| YouTrack can't find a user account that matches the author of the commit message. | The user must either use the same email address for their accounts in both YouTrack and Bitbucket or add the value that is stored as the nickname in their Bitbucket profile to the list of VCS usernames in their Hub accounts.     For more information, see [Match Change Authors and YouTrack Users](match-commit-authors-and-youtrack-users.html).   |

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 credentials 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 Repository permissions 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 email and API token of an account that is already granted admin access in the repository.    |

## See also

### User Guide

[View and Edit VCS Changes](vcs-changes.html) [Link Issues in VCS Commits](map-issues-to-vcs-change-commit.html) [Apply Commands in VCS Commits](apply-commands-in-vcs-commits.html)