Tools: YouTrack Draft - TestRail

Integrate with YouTrack

TestRail integrates with YouTrack issues so your team can link, add, and push issues between TestRail and YouTrack as bugs/defects, requirements/references, or both. 

The TestRail integration with YouTrack supports all four methods of integrating TestRail with the issue, defect, and requirements trackers:

  • Using defect URLs to link test results to YouTrack
  • Using reference URLs to link test cases to YouTrack
  • Using the defect plugin for YouTrack to push and look up YouTrack issues in the Defects field of test results
  • Using the reference plugin for YouTrack to look up YouTrack issues in the References field of TestRail entities such as test cases, test runs, and milestones

You don’t have to use all listed integration options, and you can mix and match the integration with other tools. Configuring the integration usually only takes a few minutes. This guide explains how to configure the integration and how it works.

You can find more information about TestRail’s bug, issue, and defect integrations here, or read more about TestRail’s integrations with requirements and references management systems here.

Configure the integration with YouTrack


Defect URLs

The defect URLs are used to let TestRail know how to convert a Defect ID into a URL for your YouTrack instance. There are two types of URLs: View URLs and Add URLs.

The Defect View URL is used to build a link to YouTrack based on the Defect ID, so you can simply click on an ID to open the issue directly in YouTrack.

When you set up the Defect View URLs integration with YouTrack Issues, you can paste the ID of a YouTrack issue in the Defects field of a test result and TestRail will automatically convert that ID into a clickable link to view the issue in YouTrack. This allows your team to link tests with YouTrack issues and create defect and traceability reports in TestRail.  

The Defect Add URL is used to create a link to the issue creation screen inside YouTrack. Once the URL is configured, a new Add link appears next to the Defects field in the Add Test Result dialog and the ‘Defects’ menu in TestRail’s Push Defect From Anywhere feature. This link allows you to jump to YouTrack’s New Issue form to report a new bug.

Add Defect link in ‘Add Result’ dialog

Add Defect link in Push Defect From Anywhere

If you see the ‘Add’ link, you can copy the ID of your new YouTrack issue and enter it into any Defects field inside TestRail. 

To configure YouTrack’s URLs in TestRail, select Administration > Integration. You can alternatively enter separate bug tracker URLs for each project under Administration > Projects. Use the following example URLs to configure the addresses:

YouTrack installation
Defect View Url: https://<your-server>/youtrack/issue/%id%
Defect Add Url:  https://<your-server>/youtrack/newIssue?

Note: Please make sure to replace <your_server> with the actual address of the YouTrack instance you want to integrate with.


Here, the YouTrack instance is, so the corresponding defect view and add URLs are:

Defect View URL:

Defect Add URL:

Here’s how the Defect URLs look in TestRail:

Additionally, if you have the defect plugin configured, you’ll also be able to hover over the defect ID to view the issue details directly from within TestRail.

Defect Plugin

Defect plugins can be used to implement a deeper bug tracker integration and TestRail comes with a ready-to-use YouTrack defect plugin.

To configure the defect plugin, select Administration > Integration and select YouTrack in the Defect Plugin dropdown list. The next step is to configure all the necessary connection settings in the Configuration field. Project-specific plugins and configuration settings can optionally be specified under Administration > Projects.

We strongly recommend configuring User Variables. You can learn more about configuring these in our documentation here.

With the Defect Plugin configured, the option to push a new defect will appear in the Defect from Anywhere menu, as well as in the Add Result dialog within a test run. This dialog allows you to create a new issue in YouTrack without leaving TestRail.

Once the test result is added, hovering the mouse cursor over an issue ID will open a window with useful information and status details about the issue in YouTrack.

Fill all the fields given under defect plugin settings as per the example below:

Please Note: 


permanent_token=perm:cm9vdA==.NDYtMA (Can be generated within YouTrack by clicking on Profile>Hub>Authentication>Generate new Token)
user=<username>  (Whatever the username you are signed in as within YouTrack. You can check this detail in Profile>General tab)
login=<loginname> (

Note: Plugin customizations require the YouTrack20191 Defect and Reference Plugins, available with TestRail 6.5 and later.

Defect Plugin Customizations

The YouTrack defect plugin was built to work with a standard YouTrack configuration. TestRail allows you to customize the fields which appear in the Push dialog as well as when hovering over Defect IDs. Preconfigured push fields and hover fields can be set to ‘on’ or ‘off’ in their respective [push.fields] and [hover.fields] sections, or change the order in which they appear by the fields in each section.

Please keep in mind some fields (such as the title field) are always enabled and may not appear in these sections due to always beings required by either TestRail or YouTrack.

The YouTrack Defect Plugin also supports modifying field properties as well as custom fields.

In addition to enabling, disabling, or re-organizing fields as described above, it’s also possible to change additional options per field. To do this, you would define a section for the field, such as [push.field.description] and specify additional options within this section.

label=Detailed Description

Please see below for full list and explanation of the available field options:

Option Description
api_type Specifies the type of field data returned by the YouTrack API. Can be date, integer, or float. If type is set to date, integer, or float, the api_type value should be set to the same. (Required for custom fields when type is ‘date’, ‘integer’, or ‘float’)
label Specifies the display name of the field in the Push Defect dialogue (Required for custom fields)
size Specifies whether the field is displayed as a compact field (compact) or uses the full width of the dialogue (full)
remember Specifies if previously selected values for this field should be remembered and restored the next time the Push Defect dialogue is opened
required Specifies if this field is mandatory or optional and whether users are required to enter a value for this field in the Push Defect dialogue
type Specifies the type of this field, please see section Custom fields below for a list of supported field types (Required for custom fields)


Custom fields

You can also use the above-mentioned approach to add custom fields to TestRail’s Push Defect dialogue. To do this, simply add a line with your custom field to the [push.fields] section to add a field. Custom fields are designated by customfield_<field_name>.


Then, add a [field.settings.customfield_<field_name>] section. This section is required so the plugin can push and/or retrieve data from your tool. The following is an example custom field configuration:


The following field types are supported:

Field Type
date A string field which accepts a YYYY-MM-DD or similarly structured date value. Formatting may depend on the integrated tool’s requirements
dropdown A dropdown list that allows users to select one of the multiple options
float A numerical value, with or without a decimal
integer A whole number. The maximum value is based on your external tool’s limits.
multiselect Allows users to select multiple, pre-defined options
string A small free-text for up to 250 characters
text A large free-text field without practical size limitations



The YouTrack Defect Plugin supports submitting attachments to YouTrack as well. This field can be turned on and off, but cannot be customized. To submit one or more attachments to YouTrack, simply drag the attachment to the attachments or description areas of the push dialog or click on the area to choose an attachment from your file system.


Reference URLs

The reference URLs are implemented in a very similar manner to Defect URLs described above. The primary difference is Reference URLs are used for the ‘References’ field on various TestRail entities (instead of the Defects field).

The Reference View URL is configured in the same manner as described above and allows TestRail to create a direct link to a YouTrack based on an ID entered into a References field.

The Reference Add URL is also configured in the same way as the Defect Add URL. Once configured, an ‘Add’ link will appear next to each References field in your instance or project. If you use the ‘Add’ link, you can copy the ID of your new YouTrack issue and enter it into any Defects or References field inside TestRail.

If you have the Reference plugin configured, you’ll also be able to hover over a Reference ID to view the issue details directly from within TestRail. Keep reading to learn how to use and configure the Defect and Reference Plugins.


Here, the YouTrack instance is, so the corresponding defect view and add URLs are:

Defect View URL:

Defect Add URL:

Here’s how the Defect URLs look in TestRail:

Reference Plugin

Reference plugins can be used to retrieve additional information from IDs entered into the References field of TestRail entities, such as test cases, test runs, and milestones. The Reference Plugin is configured on the References tab of the integration settings in the same manner the Defect Plugin is configured.

Note: The plugin supports hovering over Reference IDs but does not support a Push dialog for the References field. It is also possible to customize the fields which appear via link hovering and add custom fields, as described above.

If you have the Defect Plugin already configured for YouTrack, you can simply copy your [connection] and [hover.fields] sections from the Defect Plugin into the Reference plugin configuration. Alternatively, you can choose different fields to be displayed for References and Defects.

Additional Integration Customizations

TestRail also supports custom defect plugins. If your team uses TestRail Server, it is possible to futther customize the defect plugin (or build your own) to support additional field types or other data. Please see out documentation here for additional information.