Use Jira Site Import to migrate from Server to Cloud

This guide shows you how to use Jira's native site backup and restore functionality (Site Import) to move from Jira Server to Jira Cloud.

If you're planning to migrate only Jira Software, Jira Service Management (formerly Jira Service Desk), and/or Jira Work Management (formerly Jira Core), we recommend using the Jira Cloud Migration Assistant, which you can use to migrate individual projects or whole sites from Server to Cloud.

Before using Jira Site Import, evaluate which migration method is best for you. Compare Cloud migration methods

Migration planning

We recommend reviewing our Cloud migration guide before completing the steps on this page. Learn more about the Cloud migration guide

The Jira Cloud Migration Assistant's attachment migration compatibility with site import is now available. Learn how to use the Jira Cloud Migration Assistant's attachment migration with site import

Step 1: Complete the pre-migration checklist

Before attempting a test or production migration, complete the Jira site import pre-migration checklist. This will help you prepare yourself and your data for migration, and ensure you avoid common sources of migration failure. Learn more about the Jira site import pre-migration checklist

Step 2: Determine your user migration strategy

The best way to import your users and groups will depend on a few variables: what products you’re migrating, how your users and groups are currently managed in Server, and if you plan to use Atlassian Access for SCIM (user provisioning). Learn more about user migration strategies. 

Step 3: Back up your Jira Server database

This step will back up your Jira Server database in a portable XML format. If you have multiple Jira applications on the same site, for example Jira Software, Jira Core and Jira Service Management (formerly Jira Service Desk), this backup will contain all project types (Software, Business and Service) by default. 

1. Log in as a user with the Jira System Administrators permission.

2. Choose  > System.

3. Select Import & Export > Backup System to open the Jira backup page. 

4. In the File name field, type a name for your backup file.

5. Click the Backup button and wait while your Jira data is backed up. Jira will save your backup as a zipped XML archive file within the export subdirectory of the Jira application home directory (jira-home for short). Check that Jira has the necessary file system permissions to write to this location.

6. When the backup is complete, you'll see a confirmation message. You can now retrieve the file from your Server.

Step 4: Back up your Jira Server attachments, project avatars, and logos

If you want to migrate attachments, project avatars, or logos, you'll need to back them up as well. These are stored in your Jira application’s data directory, which is a sub-directory of the Jira application home directory. 

To complete this step, you'll need to create a ZIP archive of the /data/attachments, /data/avatars/, and /logos/ directories. Make sure it uses the following structure:

Step 5: Back up your Jira Cloud site

Importing your Server backup to your Jira Cloud site will overwrite all data in your Cloud site. This data cannot be recovered. So, before importing your Server backup into your Jira Cloud site, you must back up your Jira Cloud site. Make sure you download and keep a copy of the backup file. To back up your Cloud site: 

1. Log in to your Jira Cloud site with site-admin permissions.

2. Click Jira Settings > System.

3. In the Import and Export section, click Backup manager. 

4. Under the Back up for Cloud section, click Create backup for Cloud. Make sure you include attachments, avatars, and logos in the backup by selecting the checkbox.
   
   

Step 6: Import your Server database backup into Jira Cloud

Before importing:

• You may need to audit usernames or email addresses to check for errors before you can complete the import to Cloud. The primary things to review are:

  • All emails must end in a top-level domain. For example: john_doe@company isn't valid because it's missing the .com, and would block the import.

  • All emails must use a valid domain. For example: john_doe@example.com is not allowed because example.com is not recognized as a valid domain. 

  • All users must have unique email addresses.

  • Usernames starting with addon_ will need to be renamed or deleted. This prefix is reserved for Atlassian Marketplace apps. If you haven't moved from Atlassian's Cloud products in the past, you're not likely to hit this issue.

If we find invalid or duplicate emails, we’ll provide you an option to download a CSV file containing these emails. You’ll have to either:

Enter the correct email address in the NewEmail column.

Or

If you don’t want to migrate the user, you’ll need to change FALSE to TRUE in the tombstone column.

You’ll then need to upload the corrected file using the Upload CSV option and run the import again.

At this step, you may see a list of URLs for Atlassian Server sites. To make sure links point to the new Jira Cloud site instead of the old Server site after you migrate:

1. Select the URL of the Jira Server instance you're importing to Cloud from the list.

2. Then click Run import to continue with your migration.

• We recommend you also unzip the backup file and make sure it has a file structure similar to:

1. (If not already) log in to your new Jira Cloud site with site-admin permissions.

2. Click Jira Settings > System.

3. In the Import and Export section, click Import Jira Server.

4. Select Import data and select the ZIP file you downloaded in Step 2: Back up your Jira Server database. 

5. We'll check your file for errors, and ask you to choose settings for how you want your data imported.

   1. First, select your outgoing mail setting. Whichever option you choose, you can manually change after you migrate in the outgoing mail settings.

      1. You can choose to Enable outgoing mail, which allows Jira to send automated emails for interactions – for example, new comments on issues or issue transitions.

      2. If you choose to Disable outgoing mail, Jira won't send automated emails for interactions.

   2. User migration options are no longer available

      We’ve discontinued user migration options for Server to Cloud migrations using Site Import:

      • Merge with existing cloud users

      • Overwrite existing cloud users

      Use the Jira Cloud Migration Assistant to migrate users. Learn how to migrate users and groups with Jira Cloud Migration Assistant

      For any technical concerns with this change, contact us.

      1. When you've migrated users using the Jira Cloud Migration Assistant, and you want to import all other project data, select I've migrated user data using the Jira Cloud Migration Assistant.

6. Click Run import. This will take you to a page where you can track your import progress. It may take a while for your import to finish, depending on the size of your backup.

7. When the import is complete, you'll be taken to a confirmation screen.

8. Turn off the incoming mail handlers in Cloud during testing.

   By default, the incoming mail handlers are turned on after an import. This can cause mail handlers in Cloud to process emails instead of mail handlers in Server. We strongly recommend turning these off during testing to prevent mails from incorrect processing.

   You can do the following:

   1. Click Jira Settings > System.

   2. Select Global Mail Settings, and then turn off Email puller and Email processor.

   3. Select Incoming Mail, and then delete all mail servers and handlers.

   4. If you have Jira Service Management, go to Settings > Products > Email requests, and make sure the Email addresses section is empty.

9. From here, if you still need to import your media (attachments, logos, and project avatars) choose Import media. You'll need to return to the Import and Export page before managing application access. If you've already completed this step, or aren't planning to import your media, you can skip to step 6 by clicking the link to Grant application access.

Troubleshooting this step

Import error

If you see this error:

Import error

Then you may have zipped a folder containing the .xml files, instead of zipping the XML files directly. You have to clean up invalid characters in your backup before importing into Jira Cloud. Learn how to clean up invalid characters

Import stopped

During the import process, you may see it stall on the following percentages/steps: 

1. 50% - Upgrading database

2. 90% - Importing users and groups

This is going to be normal and you just need to wait for them to complete.

Search in text field not working

Search in text fields using JQL might not work in certain Jira features until background re-indexing is complete. Re-indexing may take up to 48 hours depending on the amount of data you’ve migrated. The following features could be impacted:

• Dashboards – Gadgets, Pie charts, Statistics

• Issue View

• Company Managed Projects – Boards and Backlog

• Jira Service Management – Issue counts, Issue lists, SLAs etc.

Step 7: Import your Jira Server media into Jira Cloud

1. (If not already) log in to your new Jira Cloud site with site-admin permissions.

2. Click Jira Settings > System.

3. In the Import and Export section, click Import Jira Server.

4. Choose Import media and then find and select the media ZIP you created and downloaded in Step 3: Back up your Jira Server attachments, project avatars, and logos.

5. This will take you to a page where you can track your import progress. It may take a while for your import to finish, depending on the size of your file.

6. When the import is complete, you'll be taken to a confirmation screen.

7. From here, if you still need to import more media, repeat this step until all media files are imported. Note that you may want to test that all media was imported successfully in a new tab before importing the next batch of media.

Troubleshoot this step

Importing large attachment takes a long time

Large attachment files may not import properly and can take a long time to complete.

If your file is larger than 10 GB, you may need to split up the backup into 2-5 GB chunks instead and then import each one separately. The file structure should be:

Learn how to import only part of a Jira export into Jira Cloud

Invalid file names

Make sure that all attachments have an ID with valid file name. File names with extensions aren’t valid and may cause the import to fail.

Examples:

Correct format

Incorrect format

Page reloads suddenly and there's no further progress or message shown

During the attachment import step, there are a few distinct phases, including uploading, processing, and the actual import. Large attachment files may be interrupted during the processing phase. You can identify this if the page reloads suddenly and there's no further progress or message shown.

If everything is okay, after the processing step you should see a message like:

Attention

This will import non-database content (such as attachments and avatars) into your Jira instance. You should only do this after a full database import because the full import will remove any existing data that you import using this page.

This operation could take anywhere from several minutes to several hours depending on the size and number of attachments.

Note that this operation cannot be undone.

This indicates the processing is completed. From here, click the Proceed button to finish importing your attachments.

If you notice that the import failed during the processing step, the solution is to divide the attachments into smaller ZIP files and import each file separately. Learn how to divide the attachments into smaller ZIP files

Step 8: Review and grant access to groups imported from Server

Once you've imported everything into your Cloud site, you'll need to review the groups imported from Server and decide which to grant access to. 

As a security measure, the import process won't automatically apply the default application access settings or grant access to new users. You'll need to grant the application access to these users before they can log in.

1. Log in to your new Jira Cloud site and click  Jira Settings > User management.

2. In the Site settings section, choose Product access.
   
   

3. Choose Review imported groups to review and confirm the default groups' access.

Note that during the import, the name of the default Jira Server group Jira-administrators changes to administrators in Jira Cloud.

Step 9: Re-add yourself to groups imported from Server

As a security measure, the group settings for the person performing the migration are not imported. This means the user who executed the migration will need to be added back to their previous groups. You can do this two ways, either from the Groups section or the Users section.

From the Users section

1. Go to https://admin.atlassian.com

2. If you have multiple Cloud sites, you'll need to select the Cloud site you've just migrated to.

3. In the User management section, first choose Users.

4. Find your profile.

5. Click the ... icon

6. Choose Add user to group.

7. Select the group(s) you need to be added to.

8. Click Add to Groups.

From the Groups section

1. Go to https://admin.atlassian.com.

2. If you have multiple Cloud sites, you'll need to select the Cloud site you've just migrated to.

3. In the User management section, first choose Groups.

4. Then, select the group you need to be added to.

5. Choose Add members, and add yourself to the group. 

6. Repeat as needed for the rest of your groups.

Step 10: Complete post-migration checks

Depending on the type of migration, there may be some things you need to do once your migration is finished. Learn more in the migration planning guide

Additional troubleshooting

If you've run into a problem during your migration, we're here to help. You can start by searching for known issues in our public issue tracker. There, you can find information about common issues we see with Jira migrations, including their status and suggested workarounds.

Some known issues include the following:

• Importing from Jira Server to Cloud throws ‘Unsupported Crowd Directory Error’

• Opening the Jira Issue Navigator fails with ‘Exception 500’

• Confluence links in Jira issues should be updated automatically

More information and support

We have a number of channels available to help with your migration:

• for more migration planning information, visit the Atlassian Migration Program website

• for technical issues or more support with strategy and best practices, get in touch with our support team

• for peer advice, ask the Atlassian Community

• for expert guidance, work with an Atlassian Partner

Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.