Before you migrate, check your cloud organization
We’re currently rolling out changes that may affect your migration experience. From your organization at admin.atlassian.com, if the Users list and Groups list are under the Directory tab, you have the improved user management experience. This means that the users and groups across sites will be merged under the organization. Read more about how groups and permissions are migrated. If you have any concerns, contact support.
For a test migration or UAT, we recommend that your test cloud site is not part of the organization that also hosts your prod site. The prod site should be hosted in a different organization. This is to ensure smooth migration of the relevant users and groups.
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. The process described in this article is recommended for migrating Jira Service Management (formerly Jira Service Desk) or a combination of Jira products including Jira Service Management.
If you're planning to migrate only Jira Software and/or 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.
Migration planning
We recommend reviewing our guide to planning your migration before completing the steps on this page. Then come back and start at step 1. Or read on if you've already read the planning guide.
Step 1: Complete the pre-migration checklist
Before attempting a test or production migration, complete all of the steps for Jira Site Import in the pre-migration checklist. The checklist will help you prepare yourself and your data for migration, and ensure you avoid common sources of migration failure.
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). Take time to review the possible Jira user migration strategies and determine which you'll need to use.
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.
- Log in as a user with the Jira System Administrators permission.
- Choose > System.
- Select Import & Export > Backup System to open the Jira backup page.
- In the File name field, type a name for your backup file.
- 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.
- 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:
attachments-1.zip
└─── data
├── attachments
│ ├── ProjectKey1
│ │ └── 10000
│ │ ├── IssueKey-1
│ │ ├── IssueKey-2
│ │ └── IssueKey-3
│ ├── ProjectKey2
│ └── ProjectKey3
└── avatars
└── logos
Step 5: Import your server database backup into Jira Cloud
Log in to your new Jira Cloud site with site-admin permissions.
Click
Jira Settings > System.In the Import and Export section, click Restore system.
- Select Import data and select the ZIP file you downloaded in Step 2: Back up your Jira Server database.
- We'll check your file for errors, and ask you to choose settings for how you want your data imported.
- First, select your outgoing mail setting. Whichever option you choose, you can manually change after you migrate in the outgoing mail settings.
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.
If you choose to Disable outgoing mail, Jira won't send automated emails for interactions.
Next, select whether you want to overwrite or merge users from your server site with the users on your cloud site.
Choosing to overwrite will completely replace all users from Confluence and Jira with the users in your backup file.
If you don’t see this option, you have the improved user management experience. If you need access to the Overwrite existing cloud users option or have any concerns, contact support.Choosing to merge users will also merge groups. This means that if we find a group on your server instance with the same name as a group on your cloud site (in either Jira or Confluence), we will merge the users from the server group into the cloud group. The server group users will receive the permissions of the cloud group. Make sure you check for possible permission escalation before choosing this option.
- If 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.
- First, select your outgoing mail setting. Whichever option you choose, you can manually change after you migrate in the outgoing mail settings.
- 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.
- When the import is complete, you'll be taken to a confirmation screen.
- 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
Step 6: Import your Jira Server media into Jira Cloud
(If not already) log in to your new Jira Cloud site with site-admin permissions.
Click
Jira Settings > System.In the Import and Export section, click Restore system.
- 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.
- 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.
- When the import is complete, you'll be taken to a confirmation screen.
- 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.
Troubleshooting this step
Step 7: 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.
- Log in to your new Jira Cloud site and click Jira Settings > User management.
- In the Site settings section, choose Product access.
- 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 8: 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 at https://admin.atlassian.com.
From the Users section
- Go to https://admin.atlassian.com
- If you have multiple cloud sites, you'll need to select the cloud site you've just migrated to.
- In the User management section, first choose Users.
- Find your profile.
- Click the ... icon
- Choose Add user to group.
- Select the group(s) you need to be added to.
- Click Add to Groups.
From the Groups section
- Go to https://admin.atlassian.com.
- If you have multiple cloud sites, you'll need to select the cloud site you've just migrated to.
- In the User management section, first choose Groups.
- Then, select the group you need to be added to.
- Choose Add members, and add yourself to the group.
- Repeat as needed for the rest of your groups.
Step 9: Complete post-migration checks
Depending on the type of migration, there may be some things you need to do once your migration is finished. For a full list of post-migration recommendations, refer to the Jira migration planning guide.
Troubleshooting this step
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:
- - CONFCLOUD-65038Getting issue details... STATUS
-
-
JRACLOUD-71434Getting issue details...
STATUS
Unsupported Crowd error: See Importing from Local Jira to Jira Cloud throws Unsupported Crowd Directory Error.
- 500 errors in Jira: See Opening of Jira Issue Navigator Fails with Exception 500. Once data is fixed in Jira Server, you'll need to back it up again, then import it to your cloud site following the steps on this page.
More information and support
We have a number of channels available to help you with your migration.
- For more migration planning information and FAQs, visit the Atlassian Cloud Migration Center.
- Have a technical issue or need more support with strategy and best practices? Get in touch.
- Looking for peer advice? Ask the Atlassian Community.
- Want expert guidance? Work with an Atlassian Partner.