YouTrack InCloud 2018.3 Help

Integrate with Bitbucket

You can integrate a project in YouTrack with a Bitbucket repository. A Bitbucket integration enables the following features in YouTrack:

Prerequisites

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

  • A committer's email address in YouTrack must be the same as in Bitbucket. YouTrack searches for a user account based on the email address that is registered in Bitbucket. These users must also have permission to update issues in the connected YouTrack project. If no match is found or the user does not have the required permission, the commands are not applied.

  • 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

When you enable and configure the Bitbucket integration, you define mappings between your project and a Bitbucket repository. This operation can be performed by a project administrator on a per-project basis.

An administrator can enable and manage the Bitbucket integration for any project in YouTrack. For more information, see Bitbucket Integration.

To enable the Bitbucket integration:

  1. Click the Projects link in the header to open the Projects list.

  2. From the Administration menu for your project, select VCS.

    project administration VCS integration

  3. Click the New VCS Integration button, then select bitbucket.org.
    • The New VCS Integration dialog opens in the sidebar.

      new Bitbucket VCS integration

  4. Enter the login and password for the Bitbucket account.

  5. If you are not the repository owner, provide the repository owner name. If you are the owner of the repository, leave the field blank.

  6. Click the Connect to VCS server button.
    • The New VCS Integration dialog displays settings for mapping the VCS to your project.

      Bitbucket integration settings

  7. Enter values for the following settings:

    Setting

    Description

    YouTrack Project

    Select the YouTrack project that you use to track changes to the code repository.

    Repository

    Select the repository where you store the source code that is related to the selected project.

    Committers

    Select the group that contains all of the users who can commit changes to the selected repository.

    Monitor Branches

    Enter the names of the branches that you want to monitor for changes. Use the plus sign to include a branch and the minus sign to exclude a branch. For more information, see Monitor Branches.

    Parse commits for issue comments

    To detect and generate issue comments from commit messages, enable this option. 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.

    Visible for Groups

    Select one or mor groups to restrict the visibility of VCS changes. Otherwise, the list of VCS changes is visible to any user who has permission to read issues in the project.

  8. Click the Save button.
    • The Bitbucket repository is associated with the selected YouTrack project.

      Bitbucket integration saved

    • Commits from the Bitbucket repository that mention an issue in the project are displayed in the activity stream of the mentioned issue.

Monitor Branches

Each VCS integration lets you specify which branches in the repository are monitored for changes. You can refine the selection to include or exclude specific branches.

To specify which branches are monitored for VCS changes, select an existing integration on the VCS tab and update the Monitor Branches setting.

Monitor branches vcs project

The Monitor Branches setting accepts a list of branch names or patterns. Use the following syntax to specify which branches are monitored for changes:

+|-:branch name
  • Use + to include a branch.

  • Use - 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:

    +:refs/heads/feature/*

  • To monitor all branches, leave the input field empty.

Troubleshooting

If you experience problems setting up the Bitbucket integration, see if the following condition applies.

Condition

You are unable to save the new VCS integration settings. YouTrack returns the error unable to perform operation.

Cause

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.

Solution

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: 12 October 2018

See Also