New Jira UI - 2025
Jira is updating the UI until summer 2025, in case you already have the new UI please check this article : [Xray Cloud] How can I Setup Xray with the New Jira UI (2025)?
Introduction
After installing Xray, you need to take a few steps at the Project level:
If you're not sure where to start, you can create a Demonstration Project with sample data to explore.
To enable Xray at the project level, you need to have the Browse Projects permission enabled at the Project Permission Scheme. If you do not have it, please ask your Jira Administrator for help before proceeding. You can do it for a brand-new project or an existing one.
All the operations described can be executed from within Xray Settings available on the Project Settings screen:
On your Jira Cloud instance, enter the project you wish to configure and then click Project settings (Figure 1 - 1).
Figure 1 - Project
Under Apps (Figure 2 - 1) click Xray Settings (Figure 2 - 2)
Figure 2 - Settings
Configuration
Configuring Xray Issue Types in your Project
Configuring Xray Issue Types in your project ensures that Test management is seamlessly integrated and aligned with your project needs. Proper configuration allows you to easily track Tests, Requirements, and Defects, improving visibility and control over the Testing process. This setup helps teams organize testing workflows, measure coverage, and analyze results effectively.
Before configuring Xray Issue types, determine whether your project is Team-managed or Company-managed, as the configuration steps differ for each project type.
Company-Managed Project (old Classic Project)
Tests, along with other entities, are abstracted as Jira Issue Types. Thus, you need to add them to the Issue Type Scheme used by your project:
Access the project settings as explained above (Figure 1 and 2).
Click the Add Xray Issue Types button to automatically add the available Issue Types (Figure 2 - 3).
Alternatively, you can add the Issue Types manually by clicking the Configure the Issue Type Scheme manually button (Figure 2 - 4).
Only Jira administrators can access Issue Type schemes.
If you chose the manual option, you will enter the Issue Types screen (Figure 3).
Click the Actions button (Figure 3 - 1) and then select Edit issue types button (Figure 3 - 2; be aware of the projects using it).
Figure 3 - Actions
Add Test, Precondition, Test Set, Test Execution, Sub-Test Execution Issue Types by dragging them from the Available Issue Types column (Figure 4 - 2) and dropping them on the Issue Types for Current Scheme column (Figure 4 - 1).
Once you're finished, click Save (Figure 4 - 3).
Figure 4 - Issues
Info
When a company-managed project is configured, the Testing Board may not be visible right away (Figure 5 - 1).
Figure 5 - Testing board
If this is the case, after configuring it, simply access a page containing Xray information, such as an Xray Issue of the given project or Xray Settings of that same project, and then refresh the page.
Team-Managed Project (old Next-Gen Project)
Within team-managed projects, you first need to create the necessary Issue Types manually.
On your Jira Cloud instance, enter the team-managed project you wish to configure and click Issue types (Figure 6 - 1).
Figure 6 - Issue types
New options will appear on the left side of the screen. There, click Add issue type (Figure 7 - 1).
A modal will open (Figure 7). Enter a name (Figure 7 - 2; mandatory field) and fill in the other fields (optional). Once you're finished, click Create (Figure 7 - 3).
You will see a confirmation message, and your Issue Type will appear right away.
Figure 7 - Issue types
For simplicity, you can choose the same Issue Type names as the default global Xray Issue Types. Repeat these steps for all other necessary Xray entities such as Test, Precondition, Test Set, Test Plan, and Test Execution.
You can download the icons for the Xray Issue Types below:
(I removed the Map Issue Types to Xray entities because the option Issue Types Mapping doesn't appear on the Xray settings menu)
Configuring Requirements and Defects
Configuring requirements and defects in Xray enables clear visibility into project quality and progress. By linking them to Tests, you can track requirement coverage, identify unmet needs, and address defects efficiently. This setup ensures thorough Testing, effective Issue management, and improved software quality.
In the Xray Settings screen (Figure 8), click Test Coverage (Figure 8 - 1).
Here, you can define the Covered Issue Types (i.e., the testable entities such as the Typical Requirements, User Stories, Epics) by dragging the items you want from the Available Issue Types column (Figure 8 - 2) and dropping on the Covered Issue Types column (Figure 8 - 3).
Once you're done, click Save (Figure 8 - 4).
Figure 8 - Coverage
In the Xray Settings screen (Figure 9), click Defect Mapping (Figure 9 - 1).
Here, you can define the Covered Issue Types (i.e., the testable entities). Drag the items you want from the Available Issue Types column (Figure 9 - 2) to the Defect Issue Types column (Figure 9 - 3). Once you're finished, click Save (Figure 9 - 4).
Figure 9 - Defect mapping
Learn more
Refer to the specific Project Settings page or take a look at the extensive Global Settings page if you want to fine-tune Xray or adapt it to your specific needs.