Integrate with GitLab CI/CD
Follow the instructions on this page to integrate your YouTrack project with GitLab CI/CD.
The integration with GitLab CI/CD becomes possible when you have established a connection between a YouTrack project and a VCS repository that is hosted on gitlab.com, self-hosted GitLab Community Edition (CE), or self-hosted GitLab Enterprise Edition (EE) server. To learn how to integrate YouTrack projects with GitLab repositories, see Integrate with GitLab.
The integration between YouTrack and GitLab CI/CD enables useful features in both applications:
Pull pipeline IDs from connected projects in GitLab CI/CD and automatically update the values in custom fields that store build numbers for resolved issues.
Apply commands to issues in YouTrack when GitLab CI/CD runs a job that contains the commit referencing the issue.
Before you start, verify that the authentication token that you used for the GitLab integration is valid. If you are adding a GitLab CI/CD integration to a GitLab integration set up some time ago, the token may expire in the near future. You can check the expiration date of the token and generate a new token on the Personal Access Tokens page in GitLab.
Define a GitLab CI/CD Integration Job
To start using features of the integration with GitLab CI/CD, define one or several integration jobs in YouTrack.
Each integration job must match an existing job in Gitlab CI/CD by name. You can define integration jobs in the settings of an existing GitLab integration.
To define a new GitLab CI/CD integration job:
Click the Projects link in the header to open the Projects list.
From the action menu for your project, select VCS.
Select the target GitLab integration from the list of configured integrations.
In the sidebar, scroll down to the GitLab CI/CD section.
Click the New integration button.
Add a name for the integration job. The job name will be matched with the job name in the GitLab CI/CD configuration file
.gitlab-ci.yml. If a job in GitLab CI/CD doesn't match any integration job in YouTrack, it will not be processed by YouTrack.
Click the Add button.
You have added and enabled a new integration job.
Define the settings for the new job.
To learn more about these settings, see Integration Settings.
Click the Save button.
You have defined a new integration job for the GitLab CI/CD integration.
The following settings are available for an integration job.
Pull data from assembled builds
Determines whether the integration listens for all jobs finished by GitLab CI/CD or only considers successful ones.
Add build numbers to the set of values in a custom field
Determines which custom field is populated with build numbers in the integrated YouTrack project. The selection is restricted to custom fields that store a
As GitLab CI/CD operates with pipelines instead of builds, YouTrack stores pipeline IDs instead of build numbers as custom field values.
The value for the selected field is set automatically in any issue that is updated by the integration. The settings in the Select which issues to update section of the integration determine which issues are assigned build numbers.
The following option is available:
Select which issues to update
The options in this section determine which issues are assigned build numbers by the integration. The following options are available:
If both options are enabled, build numbers are automatically assigned to issues that meet either of these two conditions.
Update selected issues
Determines whether the integration applies changes to the selected issues in addition to the automatic build number assignment. When the Apply a command option is enabled, you can enter a predefined command that is applied to all issues that are assigned build numbers.
With this command, all issues that are processed by YouTrack are assigned to the Testing subsystem and the Test in build field is set to the build number.
When you have created an integration job, the following actions are available for this job:
Opens the Edit Job Name dialog where you can edit the name of the integration job.
Removes the integration job from YouTrack. All changes made by the integration remain in place.
You can use placeholders in the Query and Command settings. These placeholders reference attributes that are stored for jobs and pipelines in GitLab CI/CD. The placeholder is replaced with the corresponding value in GitLab when the job is processed by YouTrack. The following placeholders are available:
The date and time of the job that is processed by YouTrack.
The date and time of the job prior to the one that is processed by YouTrack.
The ID of the pipeline with the job that is processed by YouTrack.
If you experience problems setting up the GitLab CI/CD integration, see if any of the following conditions apply.
Condition - The integration isn't assigning job IDs to YouTrack issues.
The webhook that connects to GitLab isn't configured to check for relevant activity or the user account that is used to establish the connection has insufficient permissions.
Select the VCS integration in the list and click the Disable button. Once the integration has been disabled, click the Enable button.
This operation has two outcomes:
The integration does not process changes because they do not align with the integration settings.
Contact YouTrack support and ask for help checking the vcs.log file.
The vcs.log file contains records of the events related to the GitLab integration. It will tell you about processed issues, applied settings, errors, and problems.