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.

Prerequisites

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 Administration 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.
An integration in YouTrack is triggered when a corresponding job in GitLab CI/CD finishes successfully.
When triggered, the integration processes all changes made in the same branch between the last processed job in GitLab CI/CD and the current one.
Note that if you run a job in one of the old pipelines in GitLab CI/CD, the integration will not process the changes backward.
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.

Integration Settings

The following settings are available for an integration job.

Option	Description
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 `build` type. 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: Include builds that don't reference any issues ⏤ Determines whether all of the pipelines are processed by the integration or only those that contain references to YouTrack issues. The pipelines that are considered for this option are affected by the Pull data from assembled build setting. When you enable this option, users can manually adjust the build numbers in issues without having to manually add the build number first.
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: Update issues that are referenced in commit messages and build comments and match the following search criteria ⏤ Determines how the integration handles issues that contain references in commit messages and build comments. Use the query input field to filter out any issues with mentions that you want to exclude from automatic build number assignment. Update any issue that matches the following search criteria ⏤ Determines which issues are assigned build numbers whether they contain issue references or not. The standard search criteria is: `State: Fixed State: Verified resolved date: ${prev.build.time} .. ${build.time}` This query ensures that only issues that are resolved since the last successful build and the current build are considered. 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. Use the `${build}` variable to reference the pipeline ID in GitLab CI/CD. For example: `Subsystem Testing Test in build ${build}` 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.

Available Actions

When you have created an integration job, the following actions are available for this job:

Action	Description
Edit	Opens the Edit Job Name dialog where you can edit the name of the integration job.
Remove	Removes the integration job from YouTrack. All changes made by the integration remain in place.

Placeholders

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:

Placeholder	Description
${build.time}	The date and time of the job that is processed by YouTrack.
${prev.build.time}	The date and time of the job prior to the one that is processed by YouTrack.
${build}	The ID of the pipeline with the job that is processed by YouTrack.

Last modified: 27 May 2021