Integrate with GitLab
Follow the instructions on this page to integrate your project with VCS repositories that are hosted on gitlab.com, self-hosted GitLab Community Edition (CE), or self-hosted GitLab Enterprise Edition (EE) server.
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.
YouTrack is accessible to inbound connections. Specifically, you need to make sure that your network doesn't block connections between your VCS server and YouTrack.
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.
If you're integrating with a GitLab CE or GitLab EE installation and want to establish a secure (HTTPS) connection with the server, you may need to import the SSL certificate for your GitLab server into YouTrack.
If your GitLab server has a valid certificate that is signed by a well-known certificate authority (CA), the JVM vendor may have already added the root (CA) certificate to the certificate store. You should be able to connect to the server without importing its SSL certificate.
If the certificate for your server is self-signed, you need to import the certificate and public key to establish a secure connection. For security, use this option only when both YouTrack and your GitLab server run on a private computer network. This operation is only available to users with Low-level Admin Read and Low-level Admin Write permissions. For details, see SSL Certificates.
Configure the GitLab Integration
The first step is to establish a connection between a project and YouTrack and a repository in GitLab. To connect with GitLab, you need to generate and store a personal access token. This token grants YouTrack access to the repository based on the access that is granted to your GitLab account.
You can use a single access token to set up multiple integrations. If you don't already have a personal access token, you can use the direct link from YouTrack to generate it during this setup procedure.
To connect to a GitLab repository:
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.
The New VCS Integration dialog opens.
For the Server type, select GitLab.
Paste the URL that points to your GitLab repository into the Repository URL input field.
- Paste your personal access token into the Personal access token input field. If you don't already have an access token, follow these steps:
Click the Generate token link to open the Personal Access Tokens page in GitLab.
Enter a name for the token.
Set the Scopes for the token. The VCS integration requires
Click the Create personal access token button.
Copy the token to the clipboard.
Switch back to the New VCS Integration dialog in YouTrack and paste the token into the Personal access token field.
- Click the Save button.
Your YouTrack project is integrated with the selected repository in GitLab.
Commits from the GitLab repository that reference an issue in the project are displayed in the activity stream of the referenced issue.
The sidebar displays additional settings for configuring the VCS integration.
To learn more about these settings, see Integration Settings.
Advanced Server Settings
If you are unable to establish a connection to your repository using the basic settings on the New VCS Integration dialog, click the Show advanced server settings link.
You only need to enter values for these settings when you haven't set up a VCS integration with the target server. If you already have a working integration with a single repository on the server, you can add integrations with other repositories without setting these parameters again.
Use the following guidelines to set the values for these settings:
This setting helps to identify the path to the GitLab repository. If the repositories for your GitLab CE or EE server are available under
To resolve this problem, enter the base URL for your GitLab server plus the context path that points to your repository. For example:
If your server environment is set up to require HTTPS authentication, select the keystore that contains the private key for your YouTrack server. This key identifies your YouTrack server when it tries to establish a connection with GitLab. This setting is only used to support HTTPS authentication as required by connections to your internal network.
The list only displays SSL keys that are already imported into YouTrack. To learn how to generate keystores files and upload them to YouTrack, see SSL Keys.
By default, the VCS integration processes changes that are committed to the repository by any user in any branch. Any user who has access to the issue in YouTrack can view these changes in the issue activity stream.
If you only want to process changes by specific users in designated branches or restrict the visibility of VCS changes in YouTrack, you can customize the integration settings. Use following settings to customize the integration:
Sets the project in which the VCS integration is active. You can switch the integration to update issues in another project without having to add a new integration.
Restricts processing to commits by members of the specified group. When set to a specific group, commits by users who are not members are not processed by the integration.
Stores the names of the branches that you want to monitor for changes.
If the address that you entered as the Repository URL when you connected to GitLab points to a specific branch, this branch is automatically added to the list of monitored branches when you set up the connection.
Parse commits for issue comments
When enabled, YouTrack detects and generates issue comments from commit messages. 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:
To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.
VCS changes visibility
Restricts the visibility of VCS changes to one or more groups of users in YouTrack. When unrestricted, the list of VCS changes is visible to any user who has permission to read the issue.
Condition — References to issues in VCS commits are not shown as VCS changes in YouTrack. Commands that are specified in VCS commits are not applied to issues in YouTrack.
The users who commit changes to the repository are not members of the Committers group in the integration settings.
Either add the committers to the specified group in YouTrack or modify the selection in the integration settings.
The users who commit changes to the repository do not have permission to update issues in the connected project.
Either add these users to the project team or grant them a role in the project that includes the Read Issue and Update Issue permissions.
The webhooks in the integrated VCS don't exist, are disabled, or are otherwise malformed.
Check the webhooks in the settings for your VCS repository. Make sure that the webhooks exist and that they are enabled.
If you suspect that there is a problem with a webhook, delete or disable it in the settings for your VCS and set up a new VCS integration in YouTrack.
Condition — You are unable to connect to your GitLab repository. Follow the instructions below to resolve the problem.
The user whose personal access token is used for authentication with GitLab does not have access to any projects in GitLab.
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 are unable to establish a connection between YouTrack and your GitLab CE/EE server. See if any of the following causes are present.
The external service is unavailable.
Verify that your GitLab server is running.
The connection is blocked by a firewall.
Open the ports in the firewall that are used by YouTrack and the GitLab server.
The GitLab server requires a secure connection.
Import the certificate for your GitLab server into YouTrack. For instructions, see SSL Certificates.
Your SSL certificate for the GitLab server has expired.
Renew and import the updated certificate into YouTrack. For instructions, see SSL Certificates.
Condition — You are unable to set up a connection to a repository on your GitLab CE/EE server and see an
HTTP 422 Unprocessable Entity error in the logs. Follow the instructions below to diagnose and resolve the problem.
The base URL for your YouTrack server uses a non-default port. For example:
Open the Allow requests to the local network from hooks and services in the Outbound requests section of the page.menu for your GitLab server and enable the
The base URL for your YouTrack server is either set to use
The best solution in this case update the base URL for your YouTrack installation to use a proper web address.
Alternatively, you can use the Java start parameter