Connect to a VCS

YouTrack lets you link your project to a version control system. YouTrack supports direct integration with GitHub, GitLab and Bitbucket.

Connections to other version control systems are supported by the Upsource and TeamCity integrations.

Upsource supports connections to repositories in Git, Mercurial, Perforce, and Subversion.
TeamCity supports connections to repositories in ClearCase, CVS, Git, Mercurial, Perforce, SourceGear Vault, StarTeam, Subversion, Team Foundation Server, and Visual SourceSafe.

You can enable the same features that are described here when an administrator connects your VCS to Upsource or TeamCity and enables the corresponding integration in YouTrack. For more information, see Upsource Integration and TeamCity Integration.

When connect your project to a version control system, the following features are enabled:

Reference an issue ID in the comments when you commit updates to the code repository. The VCS integration adds a direct link to the YouTrack issue in the change details.
The comment is automatically added to the list of VCS changes in the activity stream for the issue in YouTrack. Each VCS change includes a direct link to the change details in the code repository. For more information, see Link Issues in VCS Commits.
Enter commands in the comments for your commits and pull requests in the VCS. When you push the commit, the command is applied all of the issues that are referenced in the comment. You can use this feature to update the status or add comments to one or more issues without even opening YouTrack. For more information, see Apply Commands in VCS Commits.
(GitHub only) Add links to the repository by pasting commit hashes into the summary, description, comment, or string-type custom field in YouTrack issues.

The VCS tab in the project profile lists all of the repositories that are connected to your YouTrack project.

The general procedure for integrating a VCS consists of the following steps:

Connect to a repository. This procedure is different for each repository type.
Map the repository to your project.

Prerequisites

Your YouTrack server must be accessible from the Internet.
A committer's email address in YouTrack must be the same as in the linked repository. YouTrack searches for a user account based on the email address that is registered in the VCS. 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.

Connect to a Repository

The first step is to connect to the VCS repository.

To connect to the VCS repository:

Open your project profile and click the Edit Project link.
Select the VCS tab.
Click the New VCS Integration button and select the type of repository you want to link to your project.
- The New VCS Integration dialog opens in the sidebar.
Follow the instructions for the repository that you want to link to your project:

To connect to a GitHub repository:

Generate an OAuth token in GitHub:
- Click the Create OAuth token link below the OAuth Token field to navigate to GitHub.
- Enter a description for the OAuth token.
- Select the scopes for the OAuth token and click the Generate token button.
- Copy the token to the clipboard.
Paste the token in the OAuth Token field.
If you are not the repository owner, provide the repository owner name. If you are the owner of the repository, leave the field blank.
Click the Connect to VCS server button.
- The New VCS Integration dialog displays settings for mapping the VCS to your project.
Follow the instructions below to map the repository to your project.

To connect to a GitLab repository:

Generate a private token in GitLab:
- Click the Copy private token link below the Private Token field to navigate to GitLab.
- Copy the private token from the Profile Settings page in GitLab.
Paste the token in the Private Token field.
If you are not the repository owner, provide the repository owner name. If you are the owner of the repository, leave the field blank.
Click the Connect to VCS server button.
- The New VCS Integration dialog displays settings for mapping the VCS to your project.
Follow the instructions below to map the repository to your project.

To connect to a Bitbucket repository:

Enter the login and password for the Bitbucket account.
If you are not the repository owner, provide the repository owner name. If you are the owner of the repository, leave the field blank.
Click the Connect to VCS server button.
- The New VCS Integration dialog displays settings for mapping the VCS to your project.
Follow the instructions to map the repository to your project.

Map the Repository to Your Project

Once you have connected the VCS server, map the repository to your project.

To map the repository:

Enter values for the settings in the New VCS Integration dialog.

Setting	Description
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.
Visible for Groups	Select one or mor groups to restrict the visibility of comments and updates on the VCS Changes tab. Otherwise, the list of changes that are displayed on this tab is visible to any user who has permission to read issues in the project.

Click the Save button.
- The repository is associated with your YouTrack project.
- Commits from the repository that mention an issue in the project are displayed in the activity stream for 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.

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 a VCS integration, see if any of the following conditions apply.

Condition	(GitLab) You don't see any options in the drop-down list for the Repository setting.
Cause	The user whose private token is used for authentication with GitLab does not have access to any projects in GitLab.
Solution	Access the Members settings for your GitLab project and add this user to the project. You can also share the project with a group where this user is a member. This user does not require a specific access level — Guest access is sufficient.

Condition	(GitLab) You don't see the repository that you want to integrate with in the drop-down list for the Repository setting.
Cause	The user whose private token is used for authentication with GitLab does not have access to the project in GitLab.
Solution	Access the Members settings for your GitLab project and add this user to the project. You can also share the project with a group where this user is a member. This user does not require a specific access level — Guest access is sufficient.

Condition	(Bitbucket) 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: 7 March 2019

YouTrack Standalone 2018.2 Help