Use Jira Cloud Migration Assistant to migrate (legacy)

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 Software

• 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

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. 

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:

1. In Jira Server or Data Center go to Settings > Manage apps.

2. Choose Find new apps and search for Jira Cloud Migration Assistant.

3. Choose Install and you're all set.

To find the migration assistant:

1. Go to Settings > System.

2. In the left panel, locate the Import and Export category, and select Migrate to cloud. The Migration Assistant home screen appears.

There are four steps to create your migration path:

1. Assess your apps

2. Prepare your apps

3. Review all email domains

4. 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

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.

Learn 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

1. Select Install app for each listed app to install it on your Cloud site.

2. Read the support and privacy policy for each app.

3. Select Continue. This takes you to the Agree to app migration screen.

2.c. Agree to app migration

When you perform an app migration, the data moves from each Server app to its Cloud version on your Cloud site. The Marketplace Partner (app 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:

1. Select View policy for each app that shows as requiring your consent.
   This opens a card that:

   1. lists all the types of data the Marketplace Partner (vendor) will have access to, such as read core data or read user data.

   2. links to the Atlassian Marketplace Terms of Use, the Marketplace Partners Privacy Policy, and the Marketplace Partners Terms of Use. We strongly recommend you read this for each app you migrate.
      
      

2. Select Confirm on this card.

3. 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:

• Atlassian’s Cloud Terms of Service and Privacy Policy do not apply to any apps installed on your Cloud site.

• By installing apps on your Cloud site, you agree to the Atlassian Marketplace Terms of Use and the Marketplace Partners privacy policy and terms of use.

• You should review a privacy policy in detail before installing an app in your Cloud site. 

• You can find the privacy policy and terms of use for each app on the app listing in Atlassian Marketplace.

App migration agreement status messages

 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:

• Atlassian Marketplace Terms of Use (the same for each app)

• The Marketplace Partner Privacy Policy (unique to each app)

• The Marketplace Partner Terms of Use (unique to each app)

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. Review all email domains

Before you migrate, you must review your users' email domains to prevent migrating users from email domains you don’t recognize or trust. This improves the security of your Cloud site. The domains you select here will be applied to all your future migrations.

You can start reviewing your domains from the Migration Assistant home screen. Select Review under the Review all email domains card. This will take you to the Review all email domains screen.

This screen lists all your email domains with the number of users in each domain. You need to mark all your domains as trusted. This ensures that you migrate users only from the email domains you trust.

For each listed domain, you need to make one of the following three decisions:

You’ll need to review all your email domains and mark them as trusted. You can continue your migration without trusting all the domains, but you won’t be able to run the migration.

Once you've marked all your domains as trusted, select Done to complete the domain review and return to the Migration Assistant home screen.

If you've any previously saved migrations:

1. From the migration dashboard, you can either create a new migration or run an existing migration. A message appears telling you to review your email domains.

2. Select Review domains to review all your email domains and mark them as trusted.

3. Select Continue without reviewing if you want to review your domains later. You can continue without trusting all the domains at this stage, but you won’t be able to run the migration.

4. Assess and prepare your users

In Cloud, all users must have valid and unique email addresses. Any emails that don’t meet these requirements will block your migration. In this step, you can assess your users and identify those with invalid or duplicate email addresses. Afterwards, you’ll have a chance to decide how fix problems with these emails so you can migrate.

To find and fix invalid and duplicate email addresses:

1. On the Migration Assistant home screen, find the Assess and prepare your users card.

2. Select Begin assessing. You’ll be moved to a page with empty results.

3. To start the assessment, select Begin assessing.

Once the assessment is complete, you’ll see results similar to the following example:

You can then view the details to identify important users that should be updated in your user directory, and apply one of the automatic options to fix remaining email addresses during migration.

Learn more about assessing and preparing users

5. Migrate your data

The key steps to set up and run your migration from Server to Cloud are:

• Connect to your cloud site

• Select a migration option

• Run pre-migration checks

• Review your migration

• Migrate

To begin migrating your data:

1. On the Migration assistant home screen, select Migrate your data.
   This takes you to the Migrations dashboard.

2. Select Create new migration.

3. Review the information on How it works screen, and then select Connect to cloud to continue.

5.a. Connect to your cloud site

1. Enter a name for your migration.

2. Choose the Cloud site you would like to migrate to.

3. To continue, select Choose migration options.
   This takes you to the Migration options screen.

5.b. Migration options 

Recommendation about migration options

1. If you’re planning to pre-migrate data, for example, users and attachments, we recommend you:

   1. First, select the migration option Choose what to migrate. This gives you the flexibility to choose what you want to migrate, including options to pre-migrate data.

   2. After you’ve pre-migrated data, select the migration option Migrate all data at once to migrate all your data in a single migration.

      1. The Migration Assistant won’t re-migrate users but it will link project data to the email addresses in Cloud.

      2. 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. 

6. Migrate all data at once

Before you begin

This option requires an empty cloud site. You can:

• delete existing projects from Jira Cloud. Learn more

• start with an empty cloud site or we’ll give you an option to overwrite existing data in your cloud site. You’ll be required to create a backup for Jira Cloud (within the last 14 days) before overwriting data.

What is migrated and what isn’t migrated

See ‘Migration option: Migrate all data at once’ on What gets migrated with Jira site import.

If you chose to merge duplicated accounts on migration, the fixes won’t be applied when you migrate all data at once. All other fixes for duplicated and invalid accounts will be applied when you migrate all data at once. To make sure duplicated accounts are merged on migration, use the ‘Choose what to migrate’ option.

Supported Jira Cloud Migration Assistant version

Jira Cloud Migration Assistant 1.7.7 and higher.

To migrate all your data, on the Migration options screen, select Migrate all data at once. This takes you to the Pre-migration checks screen.

6.a. Run pre-migration checks

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 projects exist in your Cloud site. Migrating all data at once is only available when no projects exist in your Cloud site.

• assessing your data size and complexity. If your data is too large or too complex, we may recommend reducing your data size or contacting support.

• whether you have projects in trash. Migrating all data at once will permanently delete projects from trash. You won't be able to recover the deleted projects. If you don’t want your projects deleted from trash, select the migration option ‘Choose what to migrate’.

If you decide to Continue and fix later, you can come back to view the errors once you have saved your migration.

6.b. Review your migration

You can view details about what is included (users and groups / projects) in your 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.

6.c. Manage and run your migrations

Your saved migration will be listed on the migration dashboard, where you can View details, Run, Copy, Edit, and Delete it. You can also check the status of a migration, monitor the progress, or create a new one.

Migration details

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 and progress for each stage of your migration.

Migrating all data at once doesn’t include a link to download error logs from the details page.

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 migration planning guide.

6.d. Known issues

MIG-1276

7. Choose what to migrate

On the Migration options screen, when you select Choose what to migrate, this takes you to the Choose your migration options screen.

7.a. Choose your migration options

You can migrate everything together or break it up into different stages. You can choose:

• all Advanced Roadmaps plans and its linked projects or none of your Advanced Roadmaps plans

• projects, users and groups

• cross-project boards and filters

• users and groups only (without any project data)

• customers

• all or none of your apps

1. To select Advanced Roadmaps plans, select the Advanced Roadmaps plans option.
   
   

   1. 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.

   2. When you have made your selection, select Apply changes. This takes you back to the Choose your migration options screen.
      
      

2. 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 separately 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. You can also use the filter to locate inactive projects (haven’t been updated in the last 30 or 90 days).
     
     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.
     
     

3. To select cross-project boards and filters, select the cross-project boards and filters option.

   • You can migrate only cross-project boards and filters related to selected projects. If you haven’t selected all the projects that are linked to cross-projects boards and filters, the cross-project boards and filters will still be migrated to cloud. However, they’ll work only if all the linked projects are migrated to cloud.

   • You can also migrate all cross-project boards and filters present in your server instance

   • You can also choose None to skip cross-project boards and filters migration. This will not include cross-project boards and filters for migration, unless they are an issue source for any Advanced Roadmaps plans you’ve included in your migration.
     
     When you have made your selection, select Apply changes.
     This takes you back to the Choose your migration options screen.

4. 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.

   • 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.
       
       

5. 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.
     
     

6. 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 Run pre-migration checks to continue.

7.b. Pre-migration checks

In this step, the Jira Cloud Migration Assistant will review your migration and check if there are any errors or warnings. All checks are listed as part of the following groups:

• System

• Users and groups

• Customers

• Projects

• Cross-project boards and filters

• Advanced Roadmaps plans, and

• Apps

  • App vendor checks
    
    

Learn how to troubleshoot your migration

If you decide to Continue and fix later, you can come back to view the errors once you have saved your migration.

A few examples of 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

• app assessment is complete, app versions are up to date, and apps meet migration success rate criteria

7.c. 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.

7.d. Manage and run your migrations

Your saved migration will be listed on the migration dashboard, where you can View details, Run, Copy, Edit, and Delete 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.

You can also Archive a completed migration.

You can view archived migrations from the dashboard.

The table below describes the possible statuses for migrations.

Migration details

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.

Error logs

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. Learn how to troubleshoot your migration

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.

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.

Projects

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

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.