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.
The Jira Cloud Migration Assistant is an app that helps you easily move projects, users, and groups from Jira Core or Jira Software on server to the cloud. Built and maintained by Atlassian, the app is free to install and use.
Once installed, you can choose what you want to move to the cloud, start migrating at your convenience, and monitor the progress of everything throughout the migration process.
Important changes to our server and Data Center products
We’ve ended sales for new server licenses, and will end support for server on February 2, 2024. We’re continuing our investment in Data Center with several key improvements. Learn what this means for you
When to use the Jira Cloud Migration Assistant
Use the Jira Cloud Migration Assistant when:
- You are migrating Jira Software or Core from server to cloud
- You want to migrate only some projects from server to cloud.
- You are migrating to a new or existing cloud site.
Learn more about the compatibility of the Jira Cloud Migration Assistant.
The Jira Cloud Migration Assistant does not migrate Service projects or Confluence spaces. Review all the migration methods to find the one that is right for your circumstance.
Use our migration guide to prepare and plan for your migration from server to cloud.
More about the Jira Cloud Migration Assistant
Using the Jira Cloud Migration Assistant to migrate is different to using Jira Site Import. Here are some key things to be aware of before using this tool.
It doesn’t overwrite or delete any data. When the Jira Cloud Migration Assistant migrates your data, it will be added to your cloud site along with any data that is already there. It won’t delete anything from either your server or cloud sites.
- Some data is linked. When you migrate multiple times we will attempt to link your data to avoid duplication. Learn about how we link data.
Jira Core and Jira Software data only. With the latest version of the Jira Cloud Migration Assistant, you can migrate Jira Core or Software projects with most fields supported. It does not yet support Jira Service Management (formerly Jira Service Desk) or some custom fields. Check out the latest updates for what can and can’t be migrated.
Classic projects only. Migration to Jira Cloud next-gen projects is not supported.
It’s best to check what data Jira Cloud Migration Assistant will be capable of migrating before using it to run your migration.
Before you begin
Before attempting a test or production migration, ensure you've completed all of the steps for the Jira Cloud Migration Assistant 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.
If your are on Jira version 8.14, the migration assistant is automatically installed in your server instance.
Install the Jira Cloud Migration Assistant app (for Jira 7.6 or newer)
To install the app:
- In Jira Server or Data Center go to Settings > Manage apps.
- Choose Find new apps and search for Jira Cloud Migration Assistant
Choose Install and you're all set.
Alternatively, you can install it from the Atlassian Marketplace.
You can access the migration assistant by going to Settings > System > look for the Import and Export category > select Migrate to cloud.
If you’re unable to find the migration assistant, check that you’re on a supported version of Jira.
If your Jira Server site is behind a firewall, you'll need to allow access to the domain: atlassian.com
Assess and install your apps before migrating
If you have critical data managed by apps on your server, be sure to check with the app vendor about the best process to migrate that data.
Selecting the option Assess your apps will allow you to see which apps you have installed on your server. Once you've audited what is installed, you can use the table to assess your apps, in preparation to migrate.
For more information on using this table in the Jira Cloud Migration Assistant, you can refer to this information on assessing and migrating apps with the Cloud Migration Assistant.
Set up and run your migration
To set up a new migration, select Manage your migration. You'll then be able to Create a new migration.
There are five key steps to set up and run your migration from server to cloud.
The sections below describe each step in detail and explain some common errors that you may come across. If you have technical questions or issues while using the migration assistant, get in touch with our technical support team.
1. Connect to your destination Jira Cloud site
First, you’ll be asked to add a name for your migration and choose which cloud site you would like to migrate to. You need to be an admin in both your server and the destination cloud sites.
If you have already connected a cloud site, you should see it in the dropdown. If there is nothing there, you will need to either connect a new cloud site or sign up for a trial.
When you’re ready to go, check the box to allow Atlassian to move your data from your server site to your cloud site. If you’re unable to grant Atlassian this access, you won’t be able to migrate with the migration assistant and will need to do a manual import instead.
2. Choose your migration options
You have a set of tasks to choose all the relevant migration options. You can choose:
- projects, users and groups
- users and groups only (without any project data)
Before choosing what to migrate, make sure you check out what is and isn't migrated with the migration assistant.
After selecting the options, you can use this screen to view the summary of your selections and choose Edit to make changes.
You can choose to migrate all or some of your projects.
Select the project you want to add to your migration. You can search for a particular project, or select the top box to select all projects. You won’t be able to migrate projects with project keys that already exist in your Jira Cloud destination site.
If you have lots of projects and attachments, you might want to break the migration up into a few smaller migrations. This will allow you to have smaller maintenance or downtime windows.
Apart from other projects, you can also migrate archived projects. Search or use the filter to locate the archived projects.
When you've chosen all your projects, select Add to migration.
If you aren’t migrating any projects, you can proceed to select users and groups.
Users and groups
After you have selected your projects you will have the option to select your users and groups. You can’t select a subset of users without any projects. This is because we use the project data to determine which users to add to the migration.
We will never send invitation emails to your users during the migration process.
If you select Only users and groups related to the selected projects, you’ll get the option to add additional users based on project roles and groups. Use our guide to help you make a selection.
Before continuing, you will need to select whether you want to preserve group membership or migrate your users separately to their groups.
Preserve group membership. This option will add your users to their groups as part of the migration. Your users will have access to their projects and will be added to your Jira Cloud license.
Migrate users and groups separately. This option will migrate the selected users and groups, but the users will not be added to the groups as part of the migration. Your users will be given Atlassian Accounts, but they won’t have access to projects and they won’t be added to your Jira Cloud license.
Once you have made your selection, select Add to migration.
3. Check for errors
In this step, the Jira Cloud Migration Assistant will review your migration and check for common errors. It will check if:
the migration assistant is up to date
users have valid email addresses
users have unique email addresses
- groups will be merged
projects will clash
- projects, boards, and filters are publicly available and searchable online
You may also encounter other issues during the migration process; this step only checks for the issues mentioned here.
If there is a green tick then the check has passed.
If you get a warning sign then you can continue, but you need to be aware of a potential issue.
If a check comes back with a red error then you will need to resolve the error before you can run your migration.
Expand the error and warning messages to reveal more details and links to find out more.
If you have selected to migrate a subset of your users, the check may take a little longer to run as it will need to scan through all your project data.
If you decide to Continue and fix later, you can come back to view the errors once you have saved your migration.
4. Review your migration
This is the final step in setting up your migration.
You can switch tabs to view details about what is included (users and groups / projects) in your migration or to download the pre-migration report, post migration report, and error logs.
In the Logs and reports tab, you can download the pre-migration report (.zip file) to scan through data before migrating it to your cloud site. The report includes the following information:
Summary - This lists the summary data on what is expected to migrate and not migrate.
Requires attention - This lists items that require your attention, for example, items that are not supported via migration.
Users and groups - This lists users and groups that will be included in your migration.
- Configuration items - This lists all the custom fields and workflows that are part of the migration.
If everything looks correct and you want to start your migration, click Run. If you would like to start your migration later or you still have errors to fix, click Save.
If you choose to run your migration, it will still be saved to your migration dashboard. There, you can view the progress and details of all your migrations.
Once your migration is complete, you can download the post migration report (.zip file) to know the status of the migrated data in your cloud site. The report includes the following information:
- Summary - This lists the summary data on what successfully migrated and what didn't migrate.
- Requires attention - This lists items that require your attention, for example, items that were not supported via migration.
5. Manage and run your migrations
Your saved migration will be listed on the migration dashboard, where you can view details or Run it. You can also check the status of a migration, monitor the progress, or create a new one.
You can create as many migrations as you need. At this time, migrations can't be edited or deleted, so if you create a migration that can't be used, just create a new one.
SAVED Your migration is saved and ready to run.
RUNNING Your migration is currently in progress.
FINISHED All tasks in your migration have been completed.
INCOMPLETE Some tasks were completed but there are some errors or some things that couldn’t be migrated. Importantly, this status means that some data (users, groups, projects, issues etc) has been migrated and you may need to clear this data from your cloud site if you re-migrate the same projects.
FAILED We were unable to complete the migration. This might be because a project key already exists in the destination site, or the migration hit an unexpected error.
You can review all the details of your migration by selecting View details from the migration dashboard. On the details page, you will find a summary of your migration and detailed progress for each project in your migration.
If your migration is INCOMPLETE or FAILED you can download the error logs to understand the errors in more detail. Once the migration has stopped running, you will find a link to download the error logs on the top of the details page.
You can view the project on your cloud site as soon as all the project data is migrated — even if your attachments haven't finished: Select the project name on your migration details page.
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 migration planning guide.
Users and groups
To make sure your users and groups are set up correctly:
Review members of groups and approve their permissions by going to Administration > User management.
Add users to the general administrator groups if necessary. The generic groups are: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin".
If you use an external user management system, check that your users have synced correctly.
When you are ready, invite your users. Go to Administration > Users > Show details and then Resend invite. When they first log in they may be prompted to set a new password and add personal details.If you have the improved user management experience, go to Administration > Directory > Users > Show details and then Resend invite.
- We recommend providing some training or sending an onboarding email to your users to help them get familiar with their new cloud workspace.
To check that your projects have migrated successfully:
Review projects and issues, or ask your users to review their own projects.
Check for any unusual instances of Former User. This means that we were unable to match content to a user.
- Check your JQL and quick filters for any instances of the phrase (migrated). If you find this, you will need to merge the (migrated) field with the existing version in cloud for your filter to work.
Link your other Atlassian products by going to Settings (cog icon) > Jira settings > Products > Application links.
You can then install any other apps you wish to use and onboard your users.
Known issues and troubleshooting
Data integrity. If your Jira server site is highly customized, you may face additional issues when migrating. For example, if you have any required field with a null value the migration will fail because this is not supported on your cloud site. We recommend cleaning up your server data before migrating.
Extra-large projects. Single projects with more than 100,000 issues may cause the Jira Cloud Migration Assistant to time out. We recommend only migrating projects with less than 100,000 issues. You can still migrate multiple smaller projects with more than 100,000 issues between them.
Migrating all users and groups. We will migrate all your users and groups every time you run a migration. If you have lots of users and groups, this could take a significant amount of time. You can migrate up to 5000 active users and an unlimited amount of inactive users. However, the more users you migrate, the more issues you will face and the longer it will take.
- Incomplete migrations and projects. An incomplete status means that some things have been migrated but there was at least 1 entity that we couldn’t migrate. For example, we might be able to migrate a project but 1 issue fails because there is a null value in a custom field. In this case, the project will show up as incomplete even though all the actual data is complete. Many times this status will not be a problem for your migration. Download the error logs to determine what is causing the failure.
- Changes on server before migrating. If you make any changes on your server site, wait at least 10 minutes before migrating to allow all data to be updated.
- Changing projects keys. If you choose to change a project key on your server before or during migration, make sure that all configuration, filters and boards are updated with the new project key before attempting a new migration.
- Links to projects and issues not in the migration. If you have chosen to migrate in smaller batches, links to projects or issues that haven't yet been migrated will be missing until that linked item is migrated.
- History entries with missing references. If a history entry refers to a missing link or attachment, the history entry won't be migrated. If a linked issue or project is migrated at a later date, the history entry will be updated.
- Jira Software boards not returning correct results. The migration assistant does not check that the JQL issue filters on boards are returning the correct results after migration. If a board has a filter that mentions a project or field that is not yet migrated, the board may not return the same results after it is migrated. To fix this issue, edit the board's JQL filter after migrating.
- Jira new issue view. If your cloud site uses the new issue view, you might want to run some training or create a tutorial video to explain the differences that your users may experience between the two views. You can change between the old and new issue view following the steps here.
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.