YouTrack Standalone 2017.2 Help

GitLab Integration

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

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. If you use an account that does not have at least guest access to the project, you are not able to select the repository that is associated with this project.

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

As an administrator, you can enable the GitLab integration for any project in YouTrack.

To enable the GitLab integration:

  1. Open the Administration > VCS Integrations page.

  2. Click the New VCS Integration button.
    • The New VCS Integration dialog opens in the sidebar.

      ytVCSGitHubAdd thumbnail

  3. From the Server drop-down list, select gitlab.com.

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

      glGenerateToken thumbnail

  5. Return to the New VCS Integration dialog in YouTrack and paste the token in the Private Token field.

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

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

      ghIntegrationSettings thumbnail

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

    Visible for Groups

    Select one or more 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.

  9. Click the Save button.
    • The GitLab repository is associated with the selected YouTrack project.

      NewGitLabIntCreated thumbnail

    • Commits from the GitLab repository that mention an issue in the project are displayed in the VCS Changes tab of the mentioned issue.

  10. Configure the integration in GitLab.

    To set YouTrack issue IDs as links in GitLab commit messages, you need to configure this feature in GitLab. To locate this option, access the Integrations page in your GitLab project settings and select Custom Issue Tracker from the Project services list.

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

See Also