The TeamCity integration helps you reduce the amount of duplicated effort that is performed by your development teams. The integration between YouTrack with TeamCity enables useful features in both applications:
YouTrack pulls build numbers from connected projects. Issues that were resolved after the last known successful build are automatically assigned the build number of the next successful build. This value is added to a custom field that stores the build number for each resolved issue. YouTrack also adds a TeamCity icon next to each build number that is stored in the custom field. Users can click this icon to open the TeamCity build that includes the changes that resolved the issue.
You can specify whether issues that are mentioned in commit messages and build comments are assigned build numbers and use a search query to assign build numbers to issues that match specific criteria.
Your developers can reference an issue ID in the comments when they commit updates to the code repository. The TeamCity integration adds a direct link to the YouTrack issue in the change details. The comment is automatically added to the list of changes in the activity stream for the issue in YouTrack. Each VCS change includes a direct link to the change details in TeamCity.
Your developers can enter commands in the comments for their commits in TeamCity. When TeamCity assembles a build that contains the commit message, the command is applied all of the issues that are referenced in the comment. Developers can use this feature to update the status or add comments to one or more issues without even opening YouTrack.
To learn more about how to set up and use a TeamCity integration in YouTrack, watch this demo:
Enable the TeamCity Integration
For users to take advantage of these features, you must first enable and configure the TeamCity integration.
Before you start, verify the following requirements:
You have an active TeamCity installation that runs version 8.0 or later.
Your user account in TeamCity is assigned the permissions that are required for this integration. You need permission to View project and all parent projects and Modify user profile and roles. Access to these permissions is based on the authorization mode that is used by your TeamCity server.
Authorization Mode
Access Requirements
Simple
The default Administrator role has both of the permissions that are required for the integration.
Per-project
The default Project viewer role has permission to View project and all parent projects. The default Project developer and Project administrator roles include permissions for the Project viewer by default. The permission to Modify user profile and roles is not included and must be added to the role that is assigned to your account. Roles can be assigned to your account directly or at the group level.
The YouTrack projects that you want to integrate with TeamCity use 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.
If you want to add build numbers to issues that are mentioned in commits and build comments, you have enabled the Issue Tracker Integration feature in TeamCity and configured it to convert strings into links to issues in YouTrack. For more information, refer to the Team City documentation.
Set the Schedule for Pulling Data from TeamCity
YouTrack pulls data from TeamCity according to a schedule. The default interval is 10 minutes. You can change the schedule to a predefined interval or specify a custom interval with a cron expression. The schedule is not set independently for multiple TeamCity servers. The same schedule is applied to all TeamCity servers that are integrated with the YouTrack server.
To specify an interval for pulling data:
In the Integrations section of the Administration menu, select TeamCity Integration.
From the Pull fresh data drop-down menu, select a pre-configured time interval. To specify another time interval, select Custom and enter a cron expression. For example, to pull fresh data every 45 minutes, every day, use the following expression:
00/45***?
For details about cron expressions format, please refer to the cron trigger tutorial.
Configure the Connection to a TeamCity Server
To enable the integration, you need to connect to one or more TeamCity servers.
To connect to a TeamCity server:
On the TeamCity Integration Settings page, click the Add TeamCity Server link.
The Add TeamCity Server dialog opens in the sidebar.
Enter values for the following settings:
Setting
Description
URL
Enter the URL of the TeamCity server.
TeamCity Login
Enter the username of the TeamCity user account.
Password
Enter the password for the TeamCity user account.
Expand the Advanced settings section and configure the following optional settings:
Setting
Description
Select SSL key
If the TeamCity server uses a secure connection and you have uploaded an SSL client key, 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 TeamCity server before disconnecting the socket. By default, the value is set to 30 seconds.
Read Timeout
Set the maximum amount of time to wait for complete data transfer from the TeamCity server before closing the connection.
Click the Add server button.
The TeamCity server connection settings are saved.
Click the Test connection button.
YouTrack verifies the connection to the TeamCity server.
Repeat these steps to add connections to additional TeamCity servers.
Define the Mapping Between Projects
When you connect to a TeamCity server, you must create a mapping between a YouTrack project and a TeamCity build configuration. As an administrator, you can either map the projects yourself, or let the project administrators map their own projects and build configurations. For detailed instructions that are appropriate for project administrators, see Integrate with TeamCity.
The first group of settings connect YouTrack to a build configuration for a project on a TeamCity server. Additional options for the default and feature branches let you define which issues are assigned build numbers for each branch. 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 TeamCity:
Click the Create New Mapping button.
The Create Mapping dialog opens in the sidebar.
Enter values for the following settings:
Setting
Description
YouTrack Project
Select the YouTrack project that you want to map to a project in TeamCity.
TeamCity Server
Select the TeamCity server that contains the project that you want to map to. If you are only connected to one TeamCity server, it is set by default.
TeamCity Project
Select the name of the project in TeamCity.
TeamCity Build
Select a build configuration from the selected TeamCity project.
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.
Configure the following options:
Option
Description
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.
Add each build
Determines which build numbers are added to the set of values for the custom field that is stored in the Build field setting. Enable to add builds to the set of values in the build field even when there aren't any YouTrack issues that were processed in the build. The builds that are considered for this option are affected by the Failed builds setting.
Related issues
Enable to add build numbers to issues that are mentioned in commits and build comments. When disabled, YouTrack ignores mentioned issues. Use this option together with the Query setting to determine which issues are assigned build numbers.
To use this option, you must also enable the Issue Tracker Integration feature in TeamCity and configure it to convert strings into links to issues in YouTrack. For more information, refer to the Team City documentation.
Issues matching 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 Related issues option to determine which issues are assigned build numbers.
Build field
Choose the custom field in your project that stores build numbers from TeamCity. The selection is restricted to custom fields that store a build type.
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 TeamCity. 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.
Expand and set the options for the Actions for Feature Branches settings. These settings determine which actions are applied to builds in one or more feature branches. Each setting provides the same functionality as described for the default branch, above.
If you want to restrict the visibility of comments and updates on the VCS Changes tab, select one or more groups from the Visible to drop-down list. Otherwise, the list of changes that are displayed on this tab is visible to any user who has permission to read issues in the project.
Click the Create Mapping button.
The YouTrack project is mapped to the selected project in TeamCity.
The TeamCity integration is enabled and available for use in the selected YouTrack project.
Placeholders
You can use placeholders in the Query and Command settings. These placeholders reference attributes that are stored for builds in TeamCity. 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.
${revision}
The revision number that is assigned to a VCS commit.
TeamCity Integration Settings
You can access the TeamCity Integration Settings page from the Integrations section of the Administration menu.
This page displays a list of the TeamCity servers that are integrated with your YouTrack server. The table shows the name of each integrated project, a link to the connected build in TeamCity, and the number of the last processed build.
The following controls are available on this page:
Control
Description
Pull fresh data
Sets the interval for pulling fresh data from TeamCity. Select a predefined interval or specify a custom interval. To specify a custom interval, select Custom and enter a cron expression. The schedule is not set independently for multiple TeamCity servers. The same schedule is applied to all TeamCity servers that are integrated with the YouTrack server.
Create new mapping
Opens the Create New Mapping dialog in the sidebar. Use these settings to map a YouTrack project to a build configuration in TeamCity.
Run
Pulls fresh data from the TeamCity server for the selected project. Links to TeamCity builds are added to issues in YouTrack that are mentioned in build comments and commit messages. Commands in VCS commit messages are applied to the corresponding issues. Build numbers are added to issues according to the options that are defined in the mapping. The last processed build is updated in the corresponding column on the integration settings page.
Edit
Opens the settings dialog for the selected TeamCity server or mapping in the sidebar.
Remove
Deletes the selected TeamCity server or mapping from YouTrack.
Reset
Removes the IDs of the last recorded change and processed build from the selected project mapping. The next time the integration is scheduled to update, YouTrack pulls the entire change and build history from TeamCity. Changes and builds that already exist in YouTrack are not affected.
Disable
Disables the TeamCity integration in the selected TeamCity server or project. Use this option at the project level to disable integration features on a per-project basis. If the integration is disabled, the Enable option is available.
Add TeamCity Server
Opens a dialog in the sidebar that lets you define a connection with a new TeamCity server.
