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 changes on the VCS Changes tab in the YouTrack full page view. 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.

/help/img/youtrack/2017.1/ProjectVCSIntegrations_thumbnail.png

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.

/help/img/youtrack/2017.1/VCSIntegrationSettings_thumbnail.png

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.
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 VCS Changes tab of the mentioned issue.

User Guide:

Last modified: 18 April 2017

YouTrack Standalone 2017.1 Help