YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Administration
  2. Integrations
  3. Build Server Integration
  4. TeamCity Integration

TeamCity Integration

Last modified: 17 December 2019

Follow the instructions on this page to establish a connection between a YouTrack project and a build configuration in TeamCity. The integration between YouTrack and TeamCity enables useful features in both applications:

  • Pull build numbers from connected projects and automatically update the values in custom fields that store build numbers for resolved issues. Build numbers in YouTrack are appended with an icon that provides direct access to the build in TeamCity.

    fixed in TeamCity build

  • Add VCS change records to issues that are mentioned 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 TeamCity assembles a build that contains the commit. To learn how to format commands in commit messages, see Apply Commands in VCS Commits.

note

Compatibility

You can integrate YouTrack with TeamCity 8.0 and later.

To learn more about how to set up and use a TeamCity integration in YouTrack, watch this demo:

Prerequisites

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 View user profile. Access to these permissions is based on the authorization mode that is used by your TeamCity server.

    Authorization Mode

    Access Requirements

    Simple

    These permissions are only available to users with Administrator level permissions.

    Per-project

    These permissions are available to users who are assigned the default Project administrator role. TeamCity also supports a dedicated Tools integration role that includes only the permissions that are required for this integration. Roles can be assigned to your account directly or at the group level.

    For more information about roles and permissions, refer to the TeamCity documentation.

  • 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 TeamCity documentation.

Connect to a TeamCity Server

To enable the integration, you need to connect to one or more TeamCity servers. This operation can also be performed by a project administrator on a per-project basis. For more information, see Integrate with TeamCity.

As an administrator, you can enable the TeamCity integration for any project in YouTrack.

To connect to a TeamCity server:

tip

Requires permissions: Update Project

The TeamCity account that you use to set up the integration requires the following permissions in TeamCity:

  • View project and all parent projects

  • View user profile

  1. In the Integrations section of the Administration menu, select Build Server Integration.

  2. On the Build Server Integration Settings page, click the Add New Build Server link.

    • The Add Build Server dialog opens in the sidebar.

      add TeamCity server

  3. Enter values for the following settings:

    Setting

    Description

    URL

    Enter the URL of the TeamCity server.

    Type

    Select TeamCity.

    Authorization Type

    Choose which type of authorization you want to use to set up the integration. You can either use a token or sign in with a login and password.

    Token

    Enter the application token for your TeamCity user account.

    This option is only shown when the Authorization Type is set to Token.

    Login

    Enter the username of the TeamCity user account.

    This option is only shown when the Authorization Type is set to Login and password.

    Password

    Enter the password for the TeamCity user account.

    This option is only shown when the Authorization Type is set to Login and password.

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

    Setting

    Description

    SSL key

    If the TeamCity server requires 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 Keys.

    Socket timeout

    Set the maximum amount of time to wait for a response from the TeamCity 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 TeamCity server before closing the connection. The default is 30 seconds.

  5. Click the Test connection button.

    • YouTrack verifies the connection to the TeamCity server.

  6. Click the Add server button.

    • The TeamCity server connection settings are saved.

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:

tip

Requires permissions: Update Project

  1. Select a TeamCity server in the list of build server integrations.

  2. Click the Add New Mapping button.

    • The Create Mapping dialog opens in the sidebar.

      TeamCity mapping options

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

    Process changes

    Choose how YouTrack handles VCS changes in builds that are processed by TeamCity. 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

    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.

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

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

    actions for default branch

  5. Configure the options in the Process section of the form. These options determine which builds are processed by the integration and which issues are assigned build numbers.

    Option

    Description

    Failed builds

    Adds 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

    Adds build numbers to issues that are mentioned in commits and build comments. When disabled, YouTrack ignores mentioned issues.

    Use this option together with the Issues matching 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

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

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

  7. In the Apply command field, enter an optional command to apply 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.

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

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

Match VCS Commit Authors and YouTrack Users

To link VCS changes and process commands in commit messages, YouTrack has to find a user account that matches the author of the commit message. If a command is specified in the commit message, it is applied based on the access permissions that are granted to the user account in YouTrack.

For integrations with TeamCity, YouTrack checks the email address that is stored in the TeamCity user profile of the user who committed changes to the VCS. To recognize the TeamCity user who committed the change, the VCS user name should be associated with the user profile in TeamCity.

If the author of the commit message cannot be found in YouTrack, the command is not applied. The user name is shown in red text on the VCS changes tab. The warning tooltip provides information that you can use to fix the problem.

VCS user not found

There are basically two things that users can do to fix this problem:

  • Use the same email address for their accounts in YouTrack and the VCS that is connected to TeamCity.

  • Add their name (or nickname for Bitbucket) to the list of VCS user names in their Hub accounts.

    note

    GitHub and GitLab users often enter their username instead of the value that is stored as the Name in their profile. If you continue to have trouble applying commands in commit messages to your GitHub or GitLab repository, check your VCS user names for your Name.

    For example, if the legendary software engineer Linus Torvalds wanted to make sure his GitHub commits were properly linked to his VCS changes, he would need to add Linus Torvalds to the list of VCS user names in YouTrack, not torvalds, which is his username in GitHub.

See also

How-Tos

Project Administration