Connect to a VCS
YouTrack lets you link your project to a version control system. YouTrack supports direct integration with GitHub, GitLab and Bitbucket. You can also set up integrations between your YouTrack projects and self-hosted GitHub Enterprise, GitLab Community Edition (CE), GitLab Enterprise Edition (EE), Bitbucket Server, Gogs, and Gitea servers.
To set up a new integration, follow the instructions that are provided for your version control system:
| Integrate with GitHub | Integrate YouTrack project with a repository in GitHub or a GitHub Enterprise server. |
| Integrate with GitLab | Integrate YouTrack project with a repository in GitLab or a GitLab CE/EE server. |
| Integrate with Bitbucket | Integrate YouTrack project with a repository in Bitbucket. |
| Integrate with Bitbucket Server | Integrate YouTrack project with a repository in a self-hosted Bitbucket Server. |
| Integrate with Gogs | Integrate YouTrack project with a repository in a self-hosted Gogs server. |
| Integrate with Gitea | Integrate YouTrack project with a repository in a self-hosted Gitea server. |
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 a commit message when you push changes to the 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 issue-related commands in VCS commit messages. When you push the commit, the command is applied to all of the issues that are referenced in the commit message. 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.
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.
(GitHub only) Add links to the repository by pasting commit hashes into the summary, description, comment, or string-type custom field in YouTrack issues.
To learn more about how to set up and use a VCS integration in YouTrack, watch this demo:
The tab in the project profile lists all of the repositories that are connected to your YouTrack project.
The following actions are available in the toolbar:
Action | Description |
|---|---|
New VCS Integration | Lets you add a connection to a version control system or hosted VCS server. |
Disable | Shuts off the connection between the integrated project and the VCS repository. The configuration is not changed and can be re-enabled at any time. |
Edit | Opens the integration settings dialog in the sidebar. |
Delete | Removes the settings for the integrated project from YouTrack. |
Matching VCS Change Authors and YouTrack Users
To link VCS changes and process commands in commit messages, YouTrack has to find a user account that matches the author of the commit message. If a command is specified in the commit message, it is applied based on the access permissions that are granted to the user account in YouTrack.
For VCS integrations, the ability to apply commands to issues is limited to users who are members of the Committers group in the VCS integration settings.
First, YouTrack searches for a user account whose email address matches the email address of the commit author. If found, the command is executed on behalf of this user.
If none of the users in the Committers group has such an email address, YouTrack tries to find a match by name. It takes the value that is provided by the integrated VCS and compares it to the list of VCS user names that are stored in the Hub accounts for users who belong to the Committers group.
GitHub and GitLab provide the value that is stored as the Name.
Bitbucket provides the value that is stored as the Nickname.
If the author of the commit message cannot be found in YouTrack, the command is not applied. The user name is shown in red text on the VCS changes tab. The warning tooltip provides information that you can use to fix the problem.
There are basically two things that users can do to fix this problem:
Use the same email address for their accounts in YouTrack and the integrated VCS.
Add their name (or nickname for Bitbucket) to the list of VCS user names in their Hub accounts.