[Xray Cloud] Migrating Xray from one Jira Cloud instance to another. (Cloud-to-Cloud migration)

Currently, migrating Xray data between two Jira Cloud instances requires a series of manual exports and imports, as there isn’t a single, streamlined process that handles everything automatically.

To migrate those Jira-managed elements, we recommend using Atlassian’s official approach, as outlined here: Migrating from one Cloud instance to another Cloud instance. First, we would like to add that all Xray data can ultimately be migrated, not automatically or through Jira's transfer method.

It’s important to highlight that all Xray data can be migrated, but this must be done outside Jira’s native migration method.

We know the need for this functionality and have already reported a feature suggestion: XRAYCLOUD-4703 to allow migration of Xray information between Cloud instances. I recommend voting and watching the suggestions to express interest and stay updated on progress.

Before You Begin - Understand the Scope of Migration

Jira-managed data: Includes issue summaries, descriptions, custom fields, workflows, and permissions. This data is transferred using Atlassian’s Cloud-to-Cloud migration tool.
Xray-managed data: Includes test steps, test runs, links between issues (e.g., Test → Test Plan), and X-ray-specific metadata. These need to be migrated separately.

Pre-Migration Checklist

1. Xray Installation Health Check

Make sure that Xray is correctly installed on the destination Jira Cloud instance:

Go to Apps > Manage your apps.
Click on Health Check (left-side menu).
Verify that the system displays a valid status for Xray, like the screenshot below.

2. Ensure that Xray Issue Types match Across Instances

The following Xray issue types must exist and have the same names in both the source and destination instances.

To check, on the Jira Admin, go to the Work/Issues, Issues/Work Types, and search for the Xray Issue types:

Test
Test Plan
Sub Test Execution
Precondition
Test Execution
Test Set

If these issue types do not match, you may need to manually move migrated issues to the correct types after the Jira migration.

Recommended Method to migrate:

As mentioned above, to migrate the Jira data, we recommend using the Atlassian tool mentioned in this documentation: Migrating from one Cloud instance to another Cloud instance.

After using the Jira tool, you will see that all Jira data for Xray issues, such as the Issues' Summary, Descriptions, etc., were migrated. That information is not Xray managed or located in Xray Servers, so it transfers during that process. Now, what is left to do is transfer the remaining data. This is divided between three major groups, which we advise are migrated according to this order:

Xray's Issue Data : a Test's Test Steps, or Gherkin Definition; a Pre Condition's Details, etc..
Xray's Issue Relations : the association between a Test and a Test Set, a Test and a Test Execution, a Test Execution and a Test Plan, etc..
Xray's Execution's Data : all Test Run data that allows the Test Run Status and subsequent features to be calculated.

To migrate the Xray from Cloud to Cloud, you must combine manual exports and imports via Docgen & Test Case Importer and REST API & GraphQL.

There are two ways to migrate Xray from Cloud to Cloud:

Using Manual Exports and Imports: You can utilize Docgen and Test Case Importer to perform exports and imports manually. This method involves exporting entities like Test Sets, Tests, Preconditions, and Test Repository structure from the source instance and importing them with the Xray Test Case Importer.
Using Xray APIs: You can leverage a combination of REST API endpoints to import test types, test runs, and other data and the GraphQL API to transfer all Xray entities, including Tests, Test Plans, Test Executions, Test Repositories, Preconditions, and links between tests.

The difference between the options mentioned above is that using the Xray APIs is option 1; you will need to create some scripts to make this process faster and less manual. Option 2 uses Doc Gen + Test Case Import and more of the Xray APIs. The easiest way to migrate is using option 2. However, this option works only to import the Tests mentioned above, and to migrate the other Xray data you must use the Xray APIs.

For option 1,

You can use Xray's Document Generator, a built-in feature that allows you to customize templates and generate documents regarding Xray data and issues, including some Jira issues configured as requirements and defects. You can check this Knowledge Base article about Exporting and importing tests: Cloud/Cloud. There, you can download a base template to adapt to export Test, Test Set, and Pre-Condition Data and its relations.

After you export the Tests, please note that you need to perform some manual changes before importing them back to the destination instance using the Xray Test Case Importer. The only change you would have to make before the import is adding a column for the Issue ID. Below are more details.

The CSV source file must follow some simple rules. Preparing the source file. You can name the fields as you wish since they are going to be mapped during the importation process, but three mandatory fields must be mapped.
Issue Id – a unique identifier for the issue; this field is used to group lines that belong to the same test case or to identify a precondition or a test set.
Summary – this field is mandatory since Jira doesn’t allow you to create an issue without a summary.
Test Type – this field defines the test type of the each test to import. The test type must match one of the types of the project to which the test is being imported.

Finally, the remaining Relations and the Test Run's Data should be transferred by performing exports and imports with REST API and Xray's GraphQL API. This method is necessary because this data is not saved in Custom Fields but by our field entities, which default export methods or the REST API cannot handle.

Final Step: Before importing the Xray Data: Re-index the Project

After using the Jira migration tool, Xray may not immediately recognize migrated issues, and you will need to re-index the project.

To fix this:

Go to Project Settings in the destination instance
Click on Xray Settings > Re-indexing
Click Re-index and confirm the action

After re-indexing, you can import the Xray data to the destination instance.

If you have any questions or doubts, please contact the Xray Support team!

DISCLAIMER: This is not the only possible method, and you can decide to migrate the data successfully using another method. Yet, this is the analysis and strategy we recommend you follow.

Content

Space Tools