Integrate with TeamCity
If you are working on a software development project and are using TeamCity, there are some useful integration features that can reduce the amount of duplicated effort that is performed by your team. 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.
You can specify whether issues that are mentioned in commmit 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 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 on the VCS Changes tab in the YouTrack full page view. 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 command. You can use this feature to update the status or add comments to one or more issues without even opening YouTrack.
Prerequisites
Before you start, verify the following requirements:
Your YouTrack administrator has enabled the TeamCity integration for your YouTrack server and has configured the connection to a TeamCity server.
You have a user account in TeamCity that is assigned the Project Administrator role in the projects that you want to integrate with YouTrack. If your TeamCity server uses simple authorization mode, Administrator permissions are required.
- The YouTrack project that you want to integrate with TeamCity 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.
Define the Mapping Between Projects
To enable the TeamCity integration in your project, you map your YouTrack project to a build configuration in 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 Projects link in the header and select your project.
Click the Edit project link.
Select the TeamCity Integration tab.
- Click the Create New Mapping button.
The Create Mapping dialog opens in the sidebar.
- Enter values for the following settings:
Setting
Description
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 9.
- 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 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.Build Field
Select the custom field that stores the build number from TeamCity.
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.
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 your 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. |
Controls
When the integration is enabled in your project, the following controls are available on the TeamCity Integration tab:
Control | Description |
|---|---|
Create new mapping | Opens the Create New Mapping dialog in the sidebar. Use these settings to map your YouTrack project to a different build configuration in TeamCity. |
Run | Pulls fresh data from the TeamCity server. 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 to disable the integration features in your project. If the integration is disabled, the Enable option is available. |