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 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.
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 finished job	Determines whether the integration listens for all jobs finished by GitLab CI/CD or only considers successful ones.
Add pipeline IDs 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 pipelines that don't reference any issues ⏤ Determines whether all 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 referenced in commit messages, branch names, or build comments that match the following search criteria ⏤ Determines how the integration handles issues that contain references in commit messages, branch names, or build comments. Use the query input field to filter out any issues with mentions that you want to exclude from automatic build number assignment. If the option to update issues referenced in commit messages is deselected, the filter is ignored as well. 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 are: `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 the option to update issues that match the search criteria is deselected, the query is ignored as well. If both options are enabled, build numbers are automatically assigned to issues that meet either of these two conditions. If neither option is selected, the integration doesn't assign build numbers to any issues based on activity in the corresponding pipeline.
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.

Troubleshooting

The vcs.log file for your YouTrack site contains records of events related to GitLab and other VCS integrations. Check this file for information about processed issues, applied settings, errors, and problems.

If you need any help checking this file, contact YouTrack support.

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.

Cause	Solution
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: If there was a problem with the existing webhook, it is reconfigured automatically. The personal access token use to authenticate with GitLab is validated. If the token has insufficient permissions, generate another token that is granted the required permission scopes.

Cause

Solution

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:

If there was a problem with the existing webhook, it is reconfigured automatically.
The personal access token use to authenticate with GitLab is validated. If the token has insufficient permissions, generate another token that is granted the required permission scopes.

Condition — The vcs.log file reports an error similar to the following:

            24/03/22 11:29:42,465 INFO [@csJobProcessor0] [service ] [git_hosting_integration_1481972073@null] [GitLab Integration NP%3C-liubov.dievskaia/development (branch spec: )]:
            499957071 -> related issue: NP-164 not matched query 'State: Fixed State: Verified resolved date: 2022-03-24T08:29:42 .. 2022-03-24T08:29:42'
        

Cause	Solution
An issue mentioned in a commit message does not match the query in the integration settings.	Adjust the query in the settings or make the related issue match the existing query.

Condition — The vcs.log file reports an error similar to the following:

            24/03/22 11:34:50,966 INFO [@csJobProcessor0] [service ] [git_hosting_integration_1481972073@null] [GitLab Integration NP%3C-liubov.dievskaia/development (branch spec: )]:
            no suitable build processor for: test
        

Cause	Solution
The name of the job in the YAML configuration file in GitLab doesn't match any job in the integration settings.	Change the job name in the integration settings to match the name of the job in GitLab CI/CD. Alternatively, add a new integration job with the name matching a GitLab CI/CD job.

Last modified: 22 March 2024