Documents to help you prepare to migrate your Atlassian Server products.
Articles to help assess your migration costs license status.
Learn about migration timelines, roadmaps, app and Atlassian Access with these resources.
Pre-migration checklists for Jira, Confluence, and Bitbucket.
A collection of topics that help prepare you to migrate your apps to the cloud.
Native tools and resources that will help with your migration.
Documents to help you use Jira Site Import to migrate to cloud.
Documents that walk you through using the Confluence Cloud Migration Assistant to migrate to cloud.
Resources to help get started and testing after you migrate.
Documents that walk you through using the Bitbucket Cloud Migration Assistant to migrate to cloud.
Everything you need to know about moving your data from one cloud site to another.
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 helps you migrate your Server and Data Center data to a new or existing Cloud site. You can migrate:
Jira Service Management
Jira Work Management (formerly Jira Core)
Advanced Roadmaps plans with linked issue sources (projects and single-project boards). Any plans with issue sources as filters and cross-project boards is not migrated. Learn more about what is migrated and what isn’t with Advanced Roadmaps plans.
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.
If you are new to migration, use our migration guide to prepare and plan for your migration from Server to Cloud.
Before you migrate
Here are some key things to be aware of before using this app:
Data won’t be overwritten or deleted
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.
Data may get linked to avoid duplication
When you migrate multiple times we will attempt to link your data to avoid duplication. Learn about how we link data.
Using Site Import and the Jira Cloud Migration Assistant can cause data duplication
Migrating data in stages, first with Jira Site Import then followed by the Jira Cloud Migration Assistant from the same Server or Data Center instance, will cause shared configuration entities (workflows, custom fields, schemes, etc.) to be duplicated on the Cloud site. We don’t recommend this migration strategy because you will need to do a large amount of manual post-migration cleanup work.
Check the types of data that the Jira Cloud Migration Assistant can migrate 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.
Install the Jira Cloud Migration Assistant app (for Jira 7.6 or newer)
If you're on Jira version 8.14 or higher, the migration assistant is automatically installed in your Server instance.
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.
To find the migration assistant:
Go to Settings > System.
In the left panel, locate the the Import and Export category, and select Migrate to cloud. The Migration Assistant home screen appears.
If you’re unable to find the migration assistant, check that you’re on a supported version of Jira.
If your Jira Server or Data Center is behind a firewall, you'll need to allow access domains listed in IP addresses and domains for Atlassian cloud products.
This home page displays the 3 stages of assessing and creating your migration path:
Assess your apps
Prepare your apps
Migrate your data
The sections that follow explain each of these stages in detail.
If you have no apps to migrate, you can skip to step 3.
1. Assess your apps
Note about apps in ‘Stage 1’ and ‘Stage 2’
On the Assess your apps screen, apps with an ‘Automated path’ can be listed with a Stage 1 or Stage 2 label.
Stage 1: Apps in this stage have an unknown, or demonstrated low migration success rates. If you choose to migrate Stage 1 apps and the app data migration fails, you will need to contact the respective Marketplace Partner (app vendor) for support.
Stage 2: Apps in this stage have demonstrated high migration success rates.
As you assess your apps, it is important to read our docs to understand the stages of apps with automated migration paths.
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.
Use the Jira Cloud Migration Assistant to see the apps you’ve installed on your Server and assess apps in preparation to migrate. Assessing your apps and choosing alternatives (if required) for your Cloud site before migration removes the risk of your apps blocking your migration at a crucial time.
To begin assessing your apps:
On the Migration Assistant home screen, select Assess your apps.
Read more about how to use the Assess your apps screen.
When you have finished assessing your apps, select Done. This takes you back to the Migration Assistant home screen where you can choose to prepare your apps as the next step.
2. Prepare your apps
There are 3 main tasks you’ll perform at this stage:
Connect to your cloud site
Install your apps
Agree to app migration
On the Migration Assistant home screen, select Prepare your apps.
This takes you to the Connect to cloud screen.
2.a. Connect to your Cloud site
You can connect to your chosen Cloud site at this step. There are three ways to do this.
- Select your existing Cloud site from the dropdown.
- Signup for an Atlassian Free plan (max 10 users, free Cloud site).
- Set up a free product trial.
Once your destination is selected, click Continue. This takes you to the Install your apps screen.
2.b. Install your apps
Select Install app for each listed app to install it on your Cloud site.
Select Continue. This takes you to the Agree to app migration screen.
In order to complete the assessment flow, you must install the app/s you need in Cloud at this stage.
The Done button will be disabled if you have not done the following:
assigned a status to each app (on the Assess your apps screen)
installed apps needed in Cloud (on the Install your apps screen)
Complete the above tasks to enable the Done button.
2.c. Agree to app migration
When an app migration is performed, the migration moves the data from each Server app to its cloud version on your Cloud site. The Marketplace Partner (vendor) that built each app has created a migration pathway to move the data.
During this process, the Marketplace Partner will actually be performing the app data migration, not Atlassian. Because of this, you need to review, and agree to each Marketplace Partner agreement so they can access your data to migrate it.
In order to complete the assessment flow, you must provide consent and agree to app migration for each app.
On the Agree to app migration screen:
Select View policy for each app that shows as requiring your consent.
This opens a card that:
lists all the types of data the Marketplace Partner (vendor) will have access to, such as read core data or read user data.
Select Confirm on this card.
When you have performed the above action for all applicable apps, select Done to return to the Migration Assistant home screen.
You can find detailed information the third-party migration agreement in the section that follows.
Third-party migration agreement
When an app migration is performed, the migration moves the app data from each Server app to its Cloud version on your Cloud site. This can take place alongside a migration of a Confluence or Jira instance, or can be run alone.
The Marketplace Partner (vendor) that built each app has created a migration pathway to move the data, via the Atlassian platform known as the App migration platform.
It is very important to understand that the Marketplace Partner (vendor), who developed a particular app, will be performing the data migration. Atlassian has developed the App migration platform to be the conduit between the Marketplace Partner and yourself as the app user.
Data security and allowed access scopes
The App migration platform allows Server apps to export your app data to Cloud, and to access Confluence and Jira mappings. The access is very tightly controlled and restricted to a list of data types, or access scopes.
The Marketplace Partners who built the apps installed on your Server instance, have documented the access scopes required to migrate the apps.
These access scopes are surfaced in the Cloud Migration Assistant so that you can consent to the Marketplace Partner accessing this data.
You can find the specific information and list of access scopes on the Security and Access scopes pages in Atlassian’s developer documentation. For more context, read the data privacy guidelines for developers that Atlassian recommends.
Agreeing to a migration
Each Marketplace Partner app has different access scopes. You must review and agree to each Marketplace Partner agreement before they can access your data to migrate.
It’s important to know the following:
Only an app with an automated migration path needs you to agree to the migration.
If you agree to third-party migration, you can revoke your agreement at any time.
If you don’t agree to third-party migration, that app cannot be migrated using the Jira Cloud Migration Assistant.
If a Marketplace Partner updates an app, you will need to agree to the migration again.
After you agree to app migration, you can still select Revoke agreement. This will remove your agreement to third-party data migration. To agree again, click View policy and re-confirm your agreement.
Agreeing in the migration assistant
The following image shows the agreement screen included in the migration assistant for this EAP.
Some quick notes on this table:
App migration agreement status messages
What you need to know
You have agreed to third-party automated app data migration for this app.
This app is ready to be migrated.
You must review and agree to this data migration policy, or your app data cannot be migrated.
You must review the supplied Policies and Terms of Service before this app is ready to be migrated.
The policy you agreed to have been updated. Review changes and agree again before your app data can be migrated.
If a Marketplace Partner makes any changes to their policy, you’ll need to review the policy again and agree. Otherwise your app data would be migrated under conditions you hadn’t agreed to.
This app does not require an app data migration to function on your cloud site. Install it, migrate your core data and you’re ready to go.
This means there is no data contained in the app to be migrated from Server to Cloud. You can just install the Cloud version on your Cloud site.
An automated migration path between alternative app selections is not available. Contact the app vendor for migration support.
If you chose an alternative app on the app assessment table to replace an app you have on your Server, there can’t be a migration path. You’ll need to contact both Marketplace Partners if you want to migrate data from one app to another .
This app does not have an automated migration path. Contact the app vendor for migration support.
The vendor has not yet built a migration path for their apps. You should still contact the vendor, as they are likely have a manual migration process that you can follow.
This app version does not support app data migrations. You must update your Server app version in order to agree to the relevant app migration policy.
The app you have installed supports an app data migration, but you need to update your Server app to a version that supports app data migration.
When you click View policy, you will see a modal with the following details on it:
The modal above lists the following:
Access scope of that particular Marketplace Partner
All the information they will need to access/see in order to migrate this app
There are three links in each modal:
We strongly recommend you read each one for each app.
Once this is ready, you have completed your app assessment. Select Done to return to the homepage.
3. Migrate your data
There are five key steps to set up and run your migration from Server to Cloud. They are:
Connect to your cloud site
Choose your migration options
Check for errors
Review your migration
To begin migrating your data:
On the Migration assistant home screen, select Migrate your data.
This takes you to the Migrations dashboard.
Select Create new migration.
Review the information on How it works screen, and then select Connect to cloud to continue.
3.a. Connect to your cloud site
Enter a name for your migration.
Choose the Cloud site you would like to migrate to.
To continue, select Choose migration options.
This takes you to the Choose your migration options screen.
You need to be an admin in both your Server and the destination Cloud sites in order to connect to your Cloud site.
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 Site Import instead.
3.b. Choose your migration options
You can migrate everything together or break it up into different stages. You can choose:
all or none of your Advanced Roadmaps plans
projects, users and groups
users and groups only (without any project data)
all or none of your apps
If you are migrating Advanced Roadmaps
We recommend you migrate your plans first and then migrate all other projects, users, groups, customers, and apps separately. For more information about our recommendation about Advanced Roadmaps plans migration strategy, see Migrate Advanced Roadmaps plans.
Make sure you have Jira Work Management added in your destination Cloud site if you have Jira Core in your Server instance. Depending on the number of Jira Core users you've in your Server instance, you may need to upgrade to the Jira Work Management Standard plan.
To select Advanced Roadmaps plans, select the Advanced Roadmaps plans option.
On the Select Advanced Roadmaps plans screen, you’ll see the following options:
All: Migrate all your Advanced Roadmaps plans that has linked projects, boards, and filters. We don’t migrate filters.
None: No Advanced Roadmaps plans will be selected for migration.
When you have made your selection, select Apply changes. This takes you back to the Choose your migration options screen.
To select projects, select the Projects option. (If you aren’t migrating any projects, you can proceed to select users and groups.)
You can choose to migrate all or some of your projects.
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 projects into multiple migration batches. This will allow you to have smaller maintenance or downtime windows.
You can also migrate project attachments before migrating other project data. In general, the more attachments you have, the more downtime you can expect. We recommended that you migrate attachments first. This can help reduce the time window for the remaining project data migration.
By default, all project data (configurations, issues, and attachments) is selected for migration. To break your attachment and project data migration into different stages, select Attachments only. Learn how migrating attachments only reduces downtime. You will then need to migrate All project data in a later migration. This will restore the links between issues and their attachments. The migration assistant will recognize any attachments that have already been migrated and skip over these. It will still migrate new attachments, and also remove the links for any attachments that have been deleted.
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 Apply changes.
This takes you back to the Choose your migration options screen.
After you have selected your projects, you will have the option to select your users and groups.
To select users and groups, select the Users and groups option.
You can’t select a subset of users without any projects. This is because the Jira Cloud Migration Assistant must use the project data to determine which users to add to the migration. Learn more about user and group migration.
The Jira Cloud Migration Assistant also migrates the Jira Service Management agents and project administrators via the User and groups option.
Atlassian will not 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 adds 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 migrates 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.
When you have made your selection, select Apply changes.
This takes you back to the Choose your migration options screen.
After you have selected projects, you will have the option to select Jira Service Management customers. The Customers option is available only if you have Jira Service Management in your Server instance.
You can either select all Jira Service Management customers or a subset of customers related to specific projects. Learn more about customer migration.
We will not send any emails to customers when they are migrated to Cloud.
You can select the No customers option to not migrate customer accounts. This option is available when there are only Jira Software projects added or no projects are added to the migration.
To select apps for migration, select the Apps option.
On the next screen, you’ll see the following options:
All: Migrate all the apps that you marked as ‘Needed in cloud’, and which can be migrated using the Jira Cloud Migration assistant.
None: No apps will be selected for migration.
When you have made your selection, select Apply changes.
This takes you back to the Choose your migration options screen.
When you are done with choosing migration options, select Check for errors to continue.
Note: When migrating users and groups
Users are migrated using email address as the source of truth. On subsequent migrations, the migration assistant will link the data by email address rather than re-migrating them. Check out our tips for migrating a large number of users.
You must validate all your user accounts (email addresses) before migrating to Cloud. Migrating unknown user accounts can potentially allow unauthorized access to your Cloud sites. For example, if you had users in your Server instance with emails that you don’t own, say “email@example.com”, you might be inviting someone who owns “@example.com” to your site in Cloud.
Jira Cloud is subscription-based and billed on a per-user basis. If you plan to migrate your users, make sure you check the licensing options available.
If you use an external user management system, we recommend synchronizing it with your local directory before migrating. This is to make sure that your users and groups are up to date before you transfer any data.
Users with disabled status in your Server site will be migrated as active but without any product access. This means they will not be counted as active Jira users for billing purposes.
If we find a group in your Server site that has the same name as a group in your Cloud site, we will merge the users from the Server group into the Cloud group.
Global settings and global site permissions are not migrated with this tool. You’ll need to set these manually after migration.
If you have users that already exist in your destination Cloud site and you choose to migrate users with this app, the following will occur:
If a user has product access in Cloud, but has disabled status in your Server site, they will continue to have product access in Cloud after migration.
If a user does not have product access in Cloud, but is enabled in your Server site, they will be granted product access through the migration process.
If you use Jira as a knowledge base for Jira Service Management (formerly Jira Service Desk), your Jira Service Management users may also be migrated along with your Jira users. This will happen if you can see your Jira Service Management users in the cwd_user table in Jira.
3.c. Check for errors
In this step, the Jira Cloud Migration Assistant will review your migration and check if there are any errors or warnings. For example, the checks include whether:
the migration assistant is up to date
users have valid email addresses
users have unique email addresses
groups will be merged
customers have valid email addresses
customers have unique email addresses
projects will clash
projects, boards, and filters are publicly available and searchable online
All checks are listed as part of the following four groups:
Users and groups
Advanced Roadmaps plans, and
You can use our troubleshooting guide to tackle some of the common errors and warnings.
If you decide to Continue and fix later, you can come back to view the errors once you have saved your migration.
3.d. 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 / apps) 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, select Run. If you would like to start your migration later or you still have errors to fix, select 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.
3.e. 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.
The table below describes the possible statuses for migrations.
Your migration is saved and ready to run.
Your migration is currently in progress.
All tasks in your migration have been completed.
Your migration has been manually stopped. Once stopped, it can't be resumed. Any step already in progress will first need to finish before the migration is shown as fully stopped. Some projects, users, and groups may already have been migrated to your Jira Cloud site.
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.
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.
Manage your app migration
Within the migration page, you can now see an App section to monitor the progress of app migration. From this progress tracker, you can monitor the progress of the data migration of each app, and review the statuses as the migration completes.
The table below explains the various progress statuses for app migration.
The app data migration is complete, and was successful.
The app data migration is not complete
The app data migration has failed.
The app data migration is still running, and is not complete.
The app data migration is ready to run.
The app data migration is not complete. This is because the app has exceeded the permitted time period to migrate data. You can contact the respective app vendor for information on how to proceed with migrating data for the app.
If you have issues with any app for non-completion or failure to migrate, you should contact the Marketplace Partner (the app vendor) directly for support.
If your migration is incomplete or has failed, you can download the error logs to understand the errors in detail. After the migration has stopped running, you will find a link to download the error logs on the top of the details page. For more information about some of the common errors, refer to the troubleshooting guide.
After you migrate
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 Cloud migration 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.
Use JQL and quick filters to check 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
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.
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.
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.
Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.
Was this helpful?