Integrate with GitLab

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

Apply commands to YouTrack issues right from a commit comment or a pull request description. For more information, see Apply Commands in VCS Commits.
Track commits that are related to specific issues in the activity stream for each issue. For more information, see View and Edit VCS Changes.

The ability to set YouTrack issue IDs as links in commit messages is not fully supported in GitLab. The Custom Issue Tracker service that enables this feature in GitLab does not support issue URLs in the format that is used by YouTrack. All of the integration features are handled properly on the YouTrack side, but links from GitLab to YouTrack are not set correctly.

Prerequisites

Your YouTrack server must be accessible from the Internet.
The account that you use to connect to GitLab has access to the GitLab project that you want to manage with this integration. This is the user account whose private token is used for authentication. You can either use an account that has at least Master or Owner access level in the project or a GitLab administrator account.
A committer's email address in YouTrack must be the same as in GitLab. YouTrack searches for a user account based on the email address that is registered in GitLab. 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.

Configure the GitLab Integration

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

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

To enable the GitLab integration:

Click the Projects link in the header to open the Projects list.
From the Administration menu for your project, select VCS.
Click the New VCS Integration button, then select gitlab.com.
- The New VCS Integration dialog opens in the sidebar.
Generate a private token in GitLab:
- Click the Copy private token link below the Private Token field to open the User Settings page in GitLab.
- Copy the private token from the Account section of the User Settings page in GitLab.
Return to the New VCS Integration dialog in YouTrack and paste the token in the Private Token field.
If you are not the repository owner, enter the name of the owner in the Repository Owner field. 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.

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.

Click the Save button.
- The GitLab repository is associated with the selected YouTrack project.
- Commits from the GitLab 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.

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

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

Last modified: 7 March 2019

YouTrack Standalone 2018.3 Help