Integrate with Jenkins

Follow the instructions on this page to integrate your YouTrack projects with a project in Jenkins. The integration between YouTrack and Jenkins enables the following features in your project:

Pull build numbers from connected projects and automatically update the values in custom fields that store a build number.
Add VCS change records to issues that are referenced in commit messages. To learn more about VCS changes in YouTrack issues, see View and Edit VCS Changes.
Apply commands to issues in commit messages when Jenkins assembles a build that contains the commit. To learn how to format commands in commit messages, see Apply Commands in VCS Commits.

Prerequisites

Before you start, verify the following requirements:

You have a Jenkins installation that runs version 1.651.3 (1.x branch) or 2.15 (2.x branch) or later.
Your Jenkins account has read access for the views that contain the jobs that you want to connect to YouTrack.
The YouTrack project that you want to integrate with Jenkins uses a custom field that stores a value as a build type. You can use the default custom field Fixed in build or any other custom field that stores a build type.
If you don't want to add build numbers to issues, you can enable the integration without mapping build numbers to a custom field in YouTrack. In this case, your developers can still mention issues and apply commands in VCS commit messages based on the rules for processing VCS changes for the integration.
To map VCS usernames in the linked repository to user accounts in YouTrack, the project in Jenkins must be configured to use the commit author in the changelog. Use the following navigation path to locate this setting: Project > Configure > Source Code Management > Additional Behaviours > Use Commit Author In Changelog.
To enable linking from VCS changes that are shown in issue view to a diff, you need to install the Last Changes plugin in Jenkins.

Connect to a Jenkins Server

To enable the integration in your project, YouTrack needs a connection to at least one Jenkins server. If you have sufficient permissions in Jenkins, you can establish the connection yourself.

If you don't have these permissions in Jenkins, a YouTrack administrator can configure the connection. For details, see Jenkins Integration.

If YouTrack is already integrated with the Jenkins server that processes builds that contain references to your project, skip this step and define the mapping for your project.

To connect to a Jenkins server:

Click the Projects link in the header to open the Projects list.
From the Administration menu for your project, select Build Server Integration.
From the New Mapping menu, select New build server integration.
- The New Build Server dialog opens in the sidebar.
Enter values for the following settings:
Setting Description
URL Enter the URL of the Jenkins server.
Type Select Jenkins.
Username Enter the username of the Jenkins user account.
Password Enter the password for the Jenkins user account.

Setting	Description
URL	Enter the URL of the Jenkins server.
Type	Select Jenkins.
Username	Enter the username of the Jenkins user account.
Password	Enter the password for the Jenkins user account.

Expand the Advanced settings section and configure the following optional settings:

Setting	Description
SSL key	If the Jenkins server requires client SSL authentication and you have uploaded an SSL client key to authenticate your YouTrack service, select the client key from the drop-down list. For more information, see SSL Keys.
Socket timeout	Set the maximum amount of time to wait for a response from the Jenkins server before disconnecting the socket. The default is 30 seconds.
Read timeout	Set the maximum amount of time to wait for complete data transfer from the Jenkins server before closing the connection. The default is 30 seconds.

Click the Test connection button.
- YouTrack verifies the connection to the Jenkins server.
Click the Connect button.
- The Jenkins server connection settings are saved.
- The integration between your YouTrack installation and the specified Jenkins installation is enabled.

Repeat these steps to add connections to additional Jenkins servers.

Define the Mapping between Projects

To enable the Jenkins integration in your project, you map your YouTrack project to a project in Jenkins.

The first group of settings connect YouTrack to a project on a Jenkins server. Additional options for the default branch let you define which issues are assigned build numbers. You can also specify the commands to apply to all of the issues that are processed by the integration.

To define a mapping between YouTrack and Jenkins:

On the Build Server Integration tab of the Edit Project page, select a Jenkins server in the list of build server integrations.
Click the New mapping button.
- The New Mapping dialog opens.
Set the values for the mapping settings. For a complete description of each setting, see Mapping Settings.
If you want YouTrack to listen for and react to VCS changes in builds that are processed by Jenkins, expand the Processing for VCS changes settings. Otherwise, skip to the next step.
For a complete description of the settings in this section of the form, see Processing for VCS Changes.
Click to expand the Actions for Builds in the Default Branch settings. These settings determine which builds are processed by the integration and which issues are assigned build numbers.

Use these settings to configure the integration. For a complete description of each setting, see Actions for Builds.
Click the Create mapping button.
- The YouTrack project is mapped to the selected project in Jenkins.
- The Jenkins integration is enabled and available for use in your YouTrack project.

Mapping Settings

The following settings are available in the New Mapping dialog for a build server integration.

Setting	Description
Jenkins server	Select the Jenkins server that contains the project that you want to map to. If you are only connected to one Jenkins server, it is set by default.
Jenkins view	Select the name of the view that includes the Jenkins project.
Jenkins project	Select the project in the Jenkins project.

Processing for VCS Changes

The following settings are available in the Processing for VCS Changes section of the New Mapping dialog for a build server integration.

Setting	Description
VCS integration	Determines whether the integration adds VCS change records to and processes commands for issues that are referenced in commit messages. When Enabled, VCS changes that include references to YouTrack issue IDs are added to the activity stream in the referenced issue. The entry in the activity stream contains a link to the build that contains the change. When Disabled, the integration ignores all commits to the repository that is connected to the build server. Disable this option when you only want the integration to add build numbers to custom fields or have already configured an integration with the VCS directly.
Apply commands to issues	Determines whether commit messages are also parsed for YouTrack commands. When enabled, YouTrack applies any command that is specified in a commit message that is included in the assembled build to the corresponding issue. This option is only available when the VCS integration setting is Enabled. When enabled, you can select whether commands are applied to issues in all of the integrated projects, or the main project only.
Parse commits for issue comments	When enabled, specific segments of commit message text are copied to issues as comments. When you copy parts of the commit message to the issue as comments, you can trigger @mention notifications and expose information to users who don't have access to VCS changes. This setting does not affect how commit messages are shown in VCS changes. The entire commit message, including commands and issue comments, is always shown as part of the VCS change record in the activity stream. You should only enable this option when: You want to mention other users in your commit messages and generate notifications when the text is copied to an issue comment. You restrict the visibility for VCS changes and want to make commit-related information visible to external users as comments. To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.
VCS changes visibility	To restrict the visibility of comments and updates that are shown as VCS changes in the activity stream, select one or more groups or teams from the list. Otherwise, this activity type is visible to any user who has sufficient access to read the issue.

Actions for Builds

The following settings are available in the Actions for Builds section New Mapping dialog for a build server integration.

Option	Description
Pull data from assembled builds	Determines whether the integration listens for all builds that are assembled by the build server or only considers successful builds.
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. 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 builds that are processed by the integration or only those that contain references to YouTrack issues. The builds 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 build number in Jenkins. 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.

Placeholders

You can use placeholders in the Query and Command settings. These placeholders reference attributes that are stored for builds in Jenkins. The placeholder is replaced with the corresponding value in the connected version control system when the builds are processed by YouTrack. The following placeholders are available:

Placeholder	Description
${build.time}	The date and time of the build that is processed by YouTrack.
${prev.build.time}	The date and time of the build prior to the build that is processed by YouTrack.
${build}	The number of the build that is processed by YouTrack.

Last modified: 20 May 2021