TeamCity Cloud 2023.09 Help

Integrating TeamCity with Issue Tracker

TeamCity can be integrated with your issue tracker to provide a comprehensive view of your development project. TeamCity detects issues mentioned in the comments to version control changes, turning them into links to your issue tracker in the TeamCity UI.

The integration is configured at the project level: the Project Administrator permissions are required. You can configure integration if you have multiple projects on both the TeamCity and the issue tracker server or if you are using different issue trackers for different projects.

Enabling integration for the project also enables it for all its subprojects; if the configuration settings are different in a subproject, its settings have priority over the project's settings.

Dedicated Support for Issue Trackers

TeamCity supports Jira, Bugzilla, YouTrack, GitHub, GitLab, Bitbucket (Cloud, Server, Data Center), and Azure DevOps Server (formerly TFS) trackers out of the box. The Supported Platforms and Environments page lists supported versions.

When an integration is configured, TeamCity automatically transforms an issue ID (=issue key in Jira, work item ID in Azure DevOps Server) mentioned in the VCS commit comment into a link to the corresponding issue, and the basic issue details are displayed in the TeamCity web UI when hovering over the icon next to the issue ID (for example, on the Changes tab of Build Results).

Issue tracker integration

Issues fixed in the build can also be viewed on the Issues tab of the build results. You can filter the list to a particular range of builds and view issues mentioned in comments with their states.

Issue log

Since TeamCity 2020.1, integration with Jira Cloud also allows previewing build statuses directly in Jira.

Recommendations on Using Issue Tracker Integration

To get maximum benefit from the issue tracker integration, do the following:

  • When committing changes to your version control, always mention the issue ID (issue key) related to the fix in the comment to the commit.

  • Resolve issues when they are fixed (the time of resolve does not really matter).

  • Use Issue Log of a build configuration to get issues related to builds; turn on the "Show only resolved issues" option to only display the issues fixed in the builds.

Enabling Issue Tracker Integration

Requirements

The information about the issues is retrieved by the TeamCity server using the credentials provided and then is displayed to TeamCity users.

This has several implications:

  • The TeamCity server needs direct access to the issue tracker.

  • The user configured in the connection to the issue tracker has to have sufficient permissions to view the issues that can be mentioned in TeamCity. Also, TeamCity users will be able to view the issue details in TeamCity for all the issues that the configured user has access to.

Configuring connection

To enable integration, you need to create a connection to your issue tracker on the Project Settings | Issue Trackers page.

The settings described below are common for all issue trackers:

Connection type

Select the type of your issue tracker from the list.

Display name

A symbolic name that will be displayed in the TeamCity UI for the issue tracker.

Server URL (Repository URL)

The issue tracker URL

Username/Password (Authentication)

Credentials to log in to the issue tracker, if it requires authorization.

Additional authentication information or/and the details on how to specify strings to be recognized by TeamCity and converted to your tracker issue links is provided in the corresponding sections:

Converting Strings into Links to Issues

In addition to general settings, you need to specify which strings should be recognized as references to issues in your tracker.

For Jira, you need to provide a space-separated list of project keys. You can also load all project keys automatically: check the corresponding box and test the connection to your Jira server. If the connection is successful, the Project keys field will be automatically populated. Newly created projects in Jira will be detected by TeamCity, and the project keys list will be automatically synchronized.
For example, if a project key is WEB, an issue key like WEB-101, mentioned in a VCS comment, will be resolved to a link to the corresponding issue.

For YouTrack, you need to provide a permanent token for authentication and a space-separated list of Project IDs. You can also load all project IDs automatically: check Use all YouTrack IDs automatically and test the connection to your YouTrack server. If the connection is successful, the Project IDs field will be automatically populated. Newly created projects in YouTrack will be detected by TeamCity, and the project ID list will be automatically synchronized.
For example, if a project ID is TW, an issue ID like TW-18802 mentioned in a VCS comment will be resolved to a link to the corresponding issue.

For Bugzilla, GitHub, GitLab, and Bitbucket Cloud, you need to specify the Issue ID Pattern: a Java Regular Expression pattern to find the issue ID in the text. The matched text (or the first group if there are groups defined) is used as the issue number. The most common case is #(\d+) — this will extract 1234 as the issue ID from the text Fix for #1234.

TeamCity will resolve the issue number mentioned in a VCS comment and will display a link to this issue in the UI (for example, on the Changes page, or the Issues tab of Build Results).

Last modified: 07 September 2023