Integrate with Jenkins

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.

• 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:

1. Click the Projects link in the header to open the Projects list.

2. From the Administration menu for your project, select Build Server Integration.

   

3. From the Add New Mapping menu, select Add build server.

   

   • The Add Build Server dialog opens in the sidebar.

   

4. Enter values for the following settings:

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

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

   Setting	Description
   Select SSL key	If the Jenkins server uses a secure connection 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 Keystores.
   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.

6. Click the Test connection button.

   • YouTrack verifies the connection to the Jenkins server.

7. Click the Add server button.

   • The Jenkins server connection settings are saved.

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 job in Jenkins.

The first group of settings connect YouTrack to a job for 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 YouTrack.

To define a mapping between YouTrack and Jenkins:

1. On the Build Server Integration tab of the Edit Project page, select a Jenkins server in the list of build server integrations.

2. Click the Create New Mapping button.

   • The Create Mapping dialog opens in the sidebar.

   

3. Enter values for the following settings:

   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 Job	Select the job in the Jenkins project.
   Process changes	Choose how YouTrack handles VCS changes in builds that are processed by Jenkins. The following options are available: Do not attach — VCS changes that include references to YouTrack issue IDs are not added to the activity stream in the referenced issue. Use this option when you only want the integration to add build numbers to custom fields. Attach — 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. The commit message is not parsed for YouTrack commands. Attach and apply commands — 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. The commit message is also parsed for YouTrack commands.
   Visible to	To restrict the visibility of comments and updates that are shown as VCS changes in the activity stream, select one or more groups from the list. Otherwise, this activity type is visible to any user who has permission to read issues in the project.
   Parse commits for issue comments	To detect and generate issue comments from commit messages, enable this option. Otherwise, the entire commit message is displayed with the VCS change in the issue activity stream. To learn more about how YouTrack processes commit messages, see Apply Commands in VCS Commits.

4. Click to expand the Actions for Default Branch settings. These settings determine which actions are applied to builds in the default branch.

   

   If you don't want to add build numbers to issues, continue from step 6.

5. Configure the following options:

   Option	Description
   Consider failed builds	Enable to add build numbers to issues for all builds, including failed builds. When disabled, only successful builds are added to issues in YouTrack.
   Process issues mentioned in commits and build comments	Enable to add build numbers to issues that are mentioned in commits and build comments. When disabled, YouTrack ignores mentioned issues. Use this setting together with the Query setting to determine which issues are assigned build numbers.
   Query	Enter a search query to add build numbers to issues that match a specific filter criteria. The standard search query is State: Fixed State: Verified resolved date: ${build.time}..${prev.build.time}. This query ensures that only issues that are resolved since the last successful build and the current build are considered. Use this setting together with the Process issues mentioned in commits and build comments option to determine which issues are assigned build numbers.
   Command	Enter a command that is applied to all issues that are assigned build numbers in YouTrack. 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.
   Build Field	Select the custom field that stores the build number from Jenkins.
   Add builds to the set of values	Enable to automatically add build numbers to the set of values for the selected custom field. The builds that are considered for this option are affected by the Consider failed builds setting.

6. 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.

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: