Integrate TestRail with your Jira Cloud instance to push bug reports to Jira during testing, link issues to test results, look up issue details from TestRail and full requirement coverage integration. To read more about Jira and TestRail integration you can view additional information on our Jira test management page.
If you do not have a TestRail instance yet, you can register for a free trial If you are trying to set up the Jira Server plugin instead, see Connect to Jira Server.
You must be an administrative user for both TestRail and Jira Cloud or must have sufficient user privileges to configure the TestRail-Jira integration.
Configure Jira Cloud integration in TestRail
TestRail integrates with Jira so your team can link, view, add, and push issues between TestRail and Jira as bugs/defects, requirements/references, or both. The TestRail integration with Jira supports the following use cases:
- Link test cases to requirements
- Start creating requirements from TestRail
- View requirements in TestRail
- Link defects to test results
- Submit new defects in Jira
- Submit new defects from TestRail
- View defects in TestRail
You don’t have to use all the listed integration options; 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.
Configuring the Jira integration in TestRail is easy. Simply select Admin > Integration to start configuring your settings. We recommend using the simple Jira configuration wizard at the top of the page. Simply click the Configure Integration button to get started:
This will automatically help you set up the required Jira URLs, the defect integration to push/lookup Jira issues, as well as the reference/requirement integration.
- Add your Jira Instance's Base URL
https://<yoursubdomain>.atlassian.netand click Enable Jira Integration - Login/Select your user in the new Atlassian Tab that opens
- Select the same Jira Instance as used for the Base URL under Use app on* dropdown
- Click Accept
- Once the Atlassian tab closes, click Save Settings/Save Project on TestRail
Configuring the Plugin (References and Defects)
To view requirements and/or defects directly in TestRail, you need to configure the Jira References and/or Defects plugin by following the steps below. You can connect References and Defects to the same Jira Cloud instance or to different ones. Repeat the steps below for each plugin you intend to use.
- Go to the Administration page, select Integration to configure globally or Projects for a single project, and open the References or Defects tab (whichever you’re configuring).
- Select your Jira Cloud variant in the Reference Plugin drop-down list
- Click Configure Integration
- Add your Jira Instance's Base URL
https://<yoursubdomain>.atlassian.netand click Enable Jira Integration - Login/Select your user in the new Atlassian Tab that opens
- Select the same Jira Instance as used for the Base URL under Use app on* dropdown
- Click Accept
- Once the Atlassian tab closes, click Save Settings/Save Project on TestRail
Jira Issue Connect - Fields configuration
As of Testrail 10.0, once you have your plugin(s) configured, you have access to our new Jira Issue Connect capabilities. You can choose which Jira fields are displayed in TestRail for linked requirements (References) and/or defects. Keep in mind that this field configuration is exclusive for Jira Cloud only.
Go to Admin > Integration if your configuration is at an instance-level, or Projects, if it is at a project-level, and open the References or Defects tab. Select up to 5 Jira fields per plugin (References and Defects are configured independently).
Jira data shown in TestRail is synced based on the permissions of the Jira user who configures the Integration. Once stored, Jira field values may be visible to all users with access to the relevant TestRail entity, regardless of their Jira permissions.
Jira Issue Connect - Configuration Management
As of TestRail 10.0, once your plugin(s) are connected, you can manage which Jira projects are in scope and (optionally) enable real-time synchronization via a webhook. Each plugin (References/Defects) is configured independently and can point to the same or different Jira instances.
As a TestRail Admin, you can configure which Jira projects are synced and manage webhooks on an instance-level or project-level Jira integration. This way you can control data flow, avoid conflicts, and monitor integration health.
Go to Admin > Integration if your configuration is at an instance-level, or Projects, if it is at a project-level, and open the References or Defects tab. On your jira connection banner, click Manage.
The Manage button only appears after a successful OAuth2 connection. If there is no OAuth2 connection, you will see the Configure Integration button instead, or if the connection expired you will see the Refresh Connection button.
Jira projects synchronization
When you click the Manage button, the Manage Settings page opens. Here you can manage the integration settings where you can find all Jira projects to sync with TestRail and all of these are pre-selected by default.
Select the Jira projects you want to sync with this plugin. Project selection defines which Jira issues are eligible to display Jira Data in TestRail.
- All projects are preselected by default.
- Adjust the list as needed for your use case.
- Project-level settings override instance defaults for that project.
Webhooks Management
Webhooks are very light weight, fast to configure, and ideal for keeping workflows instantly in sync. Creating a webhook lets Jira immediately update data on your TestRail instance whenever an event happens, so that everything is kept fast, up-to-date, and efficient without extra effort.
To create a webhook for the configured Jira instance, you must select at least one project to enable the Create Webhook button at the end of the Manage Jira Projects page. The webhook and project settings will apply to all areas where this Jira instance is used in TestRail.
Jira only allows one webhook per user per unique endpoint per Jira instance, meaning that if a webhook already exists for a user and endpoint, you must delete or repoint it before creating a new one.
If an error occurs while trying to create or configure a webhook, a “Failed to Create Webhook” message will appear just above the form fields.
Once you create a webhook, the “Recent Deliveries” box appears on the settings page, displaying these statistics:
- Total Webhook Payloads Received
- Successful Updates Processed
- Number of Ignored/Invalid Payloads
By clicking Reset Stats underneath these statistics, all counters will be reset back to zero. To process incoming Jira updates and automatically sync relevant Jira field data into TestRail, enable the Webhook toggle. When disabled, Jira events will still be received, but no updates will be applied in TestRail. Use this option for temporary maintenance or troubleshooting.
If you want to delete a webhook, you must keep in mind that this action cannot be undone and the webhook is permanently gone (you can always create a new one, though). As an additional option, you can disable the webhook instead. However, if you do want to delete it click Delete Webhook at the end of the page, and then click Confirm in the confirmation prompt.
References
View requirements in TestRail
TestRail can retrieve additional information from Issue Keys entered into the References field of TestRail entities, such as test cases, test runs, and milestones. Simply hover over the links and a dialog will show you all the latest information without having to navigate to Jira.
When a Jira Cloud configuration for References is active, TestRail also displays a Jira Data area with the fields you selected in Jira Fields Configuration.
Link Test Cases to requirements
When establishing test coverage, while creating or modifying test cases, just include one or more Issues Keys (separated by commas) in the References field.
If you have a jira cloud integration and a webhook is properly configured, you will be able to view the Jira data from a Jira issue updated in real time, even if that issue was configured inside a Jira instance, and not in TestRail.
The References you set in your test cases will be converted to a direct link to Jira issues.
Start creating requirements from TestRail
Jira issues can serve as a source of requirements, making them valuable references for test cases. TestRail offers a convenient Add link feature within the test case editor view, enabling seamless navigation to the Jira issues screen. This feature expedites the process of creating new requirements that you wish to associate with your test cases. It's important to remember that once you've created a new requirement ( i.e., Jira issue) , you should copy and paste its issue key into the References field for proper traceability.
Defects
Submit new defects from TestRail
To enhance the seamless integration of defect reporting, TestRail offers a pre-configured Jira defect plugin. This plugin empowers you to effortlessly submit new issues to Jira directly from within TestRail.
You can customize your Jira integration by specifying default values for fields and ensuring security. These values can be set for Jira push fields to automatically populate them by default with the variables that you want. You can do this on a Project level (Admin > Projects > Set default values for Jira push fields) or on an Instance level (Admin > Integration > Set default values for Jira push fields) and click Add Default Field.
Inside the prompt, you can select the Field where you want to add the default value from the drop-down arrow, and fill in your desired Default value that will automatically show from now on. You can click Save and Close to keep the entered values and return to the previous screen, or click Save and New to keep the entered values but opens a brand new prompt to add a new set of default values once again. In both cases, a success message should appear in the upper part of the screen.
By utilizing the intuitive Push Defect dialog, you can swiftly generate a fresh defect complete with a title, description, and any additional fields that Jira supports. This streamlined process ensures a smoother defect management workflow.
You can open the defect submission dialog from two places - the Defects menu and the Add Test Result dialog.
The Defects menu, also known as TestRail’s Defect From Anywhere feature, is displayed on top of most pages for quick access.
The Add Test Result dialog displays the Push link next to the Defects field to efficiently report a defect while you're submitting your test results.
Submit new defects in Jira
TestRail provides quick navigation to report defects using the Jira interface. You can do it from two different places - the Defects menu and the Add Test Result dialog.
The Defects menu, also known as TestRail’s Defect From Anywhere feature, is displayed on top of most pages for quick access.
The Add Test Result dialog displays the Add link next to the Defects field for quickly and conveniently navigating to Jira in order to submit a defect when your test is failing.
View defects in TestRail
You can simply click on an issue key to open the issue directly in Jira.
When you set up the Defect integration with Jira Issues, you can paste the ID of a Jira 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 Jira. This allows your team to link tests with Jira issues and create defect and traceability reports in TestRail
If the webhook is properly configured, you will be able to view the Jira data from a Jira issue updated in real time, even if that issue was configured inside a Jira instance, and not in TestRail.
Advanced customizations
User Level Integration
Users can configure their user-level integration for any instances/projects that they belong to, and which have an active Jira Cloud Integration. This allows users to push Defects to Jira using their own Jira user. User-level configuration overrides project/instances configuration.
To achieve this, users have to:
- Go to the My Settings page
- Navigate to the Configuration tab
- Click on Configure Integration next to the relevant project
Keep in mind that enhanced Jira fields can only be configured at an instance or project level, not at user level.
Manual Jira configuration
Do you prefer to configure the Jira integration manually or need to customize, extend, or change the integration? You can also easily configure the Jira integration from TestRail’s side manually with a few simple steps.
You can also configure different integrations for different projects. To do so, simply configure the integration for each project under Admin > Projects > Edit a project > Defects / References tabs. Learn more about configuring the integration manually or how to customize and adjust the integration here:
- Manual Jira configuration
- Jira custom fields and issue links
- Defect variables to map users
- Building a custom defect plugin
Get the "TestRail Integration for Jira" app
The "TestRail Integration for Jira" app allows you to directly review related test results, test case links, TestRail dashboard statistics and new case buttons directly from inside Jira. To get started, simply activate the TestRail add-on for Jira Cloud from the Atlassian Marketplace:
Activate TestRail add-on from Atlassian Marketplace
Alternatively, you or your Jira administrator can enable the add-on within your Jira instance by navigating to Settings > Apps > Find New Apps, then search for TestRail. From there, click the TestRail app > Get App > Get It Now.
Next, configure the add-on with your TestRail address and key.
- Click the Apps dropdown in the top menu.
- Select Manage apps and expand the TestRail for Jira Test Management app.
- Click Configure. Then add your TestRail address and integration key and any additional optional settings.
You can also limit the add-on to select Jira user groups or projects to hide the integration from users who don’t currently use TestRail.