Documents to help you prepare to migrate your Atlassian Server products.
A collection of topics that help prepare you to migrate your apps to the Cloud.
Ensure you’re ready to migrate with these pre-migration checklists for Jira, Confluence, and Bitbucket Server or Data Center.
Documents that walk you through using the Confluence Cloud Migration Assistant to migrate to Cloud.
Documents that walk you through using the Bitbucket Cloud Migration Assistant to migrate to Cloud.
Documents to help you use Jira Site Import to migrate to Cloud.
Resources to help get started and testing after you migrate.
Everything you need to know about moving your data from one cloud site to another.
Upgrade to Confluence Cloud Migration Assistant 3.3.7 or higher and Confluence Server / Data Center 6.15 or higher
To give you a more stable and reliable migration experience, we’ve improved the way attachments and other media files are migrated.
Starting September 19, 2022, we recommend you upgrade to:
Confluence Cloud Migration Assistant 3.3.7 or higher
Confluence Server or Data Center 6.15 or higher before using the Confluence Cloud Migration Assistant
Starting January 31, 2023, you won’t be able to use:
Confluence Cloud Migration Assistant 3.3.6 and lower
Confluence Server / Data Center 6.14 and lower when using the Confluence Cloud Migration Assistant
For any further details or technical concerns, contact us.
The Confluence Cloud Migration Assistant is an app that helps you easily move content, users, and groups from Confluence Server or Data Center to Confluence Cloud. Built and maintained by Atlassian, the app is free to install and use.
With the app, 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.
When to use the Confluence Cloud Migration Assistant
Use the Confluence Cloud Migration Assistant when:
you want to move users or data from Confluence Server or Data Center to Confluence Cloud
you want to assess your apps before moving from Confluence Server or Data Center to Confluence Cloud
you want to run a test or trial migration from Confluence Server or Data Center to Confluence Cloud
the Atlassian Support team has recommended using the app
The Confluence Cloud Migration Assistant will not work for Jira products. You can download the Jira Cloud Migration Assistant for Jira migrations to Cloud.
Before you begin
Make sure you have reviewed the Cloud migration guide. This guide will walk you through the migration process step-by-step and help you identify what to look out for.
Before attempting a test or production migration, ensure you've completed the pre-migration checklist for the Confluence Cloud Migration Assistant. The checklist will help you prepare yourself and your data for migration, and ensure you avoid common sources of migration failure.
Install the Confluence Cloud Migration Assistant app
If your Confluence Server site is version 6.13 or above you won't need to install anything as the Confluence Cloud Migration Assistant comes pre-installed, although you may be asked to update the app.
To install the app on versions 5.10 to 6.12:
In Confluence Server, go to > Manage apps.
Choose Find new add-ons.
Search for the Confluence Cloud Migration Assistant.
Choose Install and you're all set.
Alternatively, you can install it from the Atlassian Marketplace.
Locate the Migration Assistant
To find the Migration Assistant:
Go to Confluence Administration > look for the Atlassian Cloud category > select Migration Assistant.
If your Confluence Server site is behind a firewall, you'll need to allow access to the domain: atlassian.com
This home page displays the three 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.
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 Marketplace Partner (app vendor) about the best process to migrate that data.
Use the Confluence 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.
Our docs provide step-by-step instructions on how to assess apps with the Confluence Cloud Migration Assistant.
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 three 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 link 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)
Once your destination is selected, click Continue.
2.b. Install your apps
On the Install your apps screen:
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.
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 more detailed information about this on the Introduction to third-party migration agreement.
It’s important to know that:
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 can't be migrated using the Confluence 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.
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
viewed and agreed to the policy for each app on the Agree to app migration screen
Once this is ready, you have completed your app assessment. Click Done to return to the homepage.
Pre-migration checks for possible data conflicts in your Cloud site
You can reduce the risk of running into issues, or the migration failing, if you conduct some manual checks in your Server and Cloud sites.
1. Check for group conflicts
Make sure that there are no groups already in your Cloud site with the same name as groups from your Server site, unless you are intentionally trying to merge them.
If we find a group in your Server site that has the same name as a group in your Cloud site (either Jira or Confluence), we will merge the users from the Server group into the Cloud group. The Server group users will inherit the permissions of the Cloud group. This also applies to groups with Jira product access that have the same name as a Confluence group you are migrating. This is because all users and groups are managed in a central location in your Cloud site.
If you don’t want this to happen, you’ll need to make sure all groups across Server and Cloud have unique names before running your migration.
The following groups manage admin access and are blocklisted. They will not be migrated at all: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin". Users in these groups will still be migrated, so if you want them to be in one of the blocklisted groups you’ll need to manually add them after migration.
2. Check for space key conflicts
Before migrating, check that there are no spaces with the same space key between your Server and Cloud sites.
If a space from your Server site has the same space key as a space in your Cloud site your migration will fail. This is because every space in Confluence Cloud must have a unique space key. If you find a conflict you can:
choose not to migrate these spaces
If the migration assistant finds a conflict, the space will not migrate.
If a space key conflict is caused by a previous test migration you can reset your cloud site before migrating.
3. Migrate your data
There are five key steps to set up and run your migration from Server or Data Center to Cloud. They are:
Connect to Cloud
Choose what to migrate
Check for errors
Review your migration
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, contact our support team.
Running a test migration
We strongly recommend doing a trial run of your migration to a test or staging site before running your final migration. Check out our guidance on testing 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. This takes you to the How it works screen.
Review the information on this screen, and select Connect to Cloud to continue.
1. Connect to your Cloud site
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 new Cloud license.
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 space import instead.
2. Choose what to migrate
You can migrate everything together or break it up into phases.
You can choose:
spaces (and their attachments), or skip migrating spaces
all or some of your users and groups from the Confluence directory
all or some of your spaces (and their attachments)
all apps that you marked as Needed in Cloud when assessing your apps
You can choose to migrate space attachments before migrating other space data. In general, the more attachments you have, the more downtime you can expect. We recommend that you migrate attachments first. This can help reduce the time window for the remaining space data migration.
When you select Migrate attachments only, this means you can only migrate attachments related to the selected spaces. Learn how migrating attachments only reduces downtime
You will then need to Migrate spaces at a later time. This will restore the links between spaces and their attachments. The migration assistant will recognise 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.
Users and groups
For a test migration or UAT, we recommend that your test Cloud site is not part of the organisation that also hosts your prod site. The prod site should be hosted in a different organisation. This is to ensure smooth migration of the relevant users and groups.
You can choose to either migrate all or some of your users.
If you choose the migrate your users, the first time you do so all your users will be added to your Cloud site. Every migration, after the first, we will just link your data to the users that already exist in Cloud. Follow our recommendations if you need to migrate a large userbase.
When you migrate your users, they will be added to their groups when they get to Cloud. You will need to review and approve group permissions after you migrate. When you approve group permissions, your users will be given Confluence access and will be added to your bill.
We won’t send an invitation to your users. To invite your users you can choose to send an invitation from the Administration space after you have migrated, or send a link for them to log in themselves.
When you choose Migrate users related to the selected spaces under users and groups, we will still migrate some user data connected to the spaces you are migrating. This is to make sure that mentions, comments, and page history stay active.
User data that will be migrated every time includes:
username (discarded after migration)
We will only migrate this information for users directly connected to the spaces you are migrating. We will not give these users product access or add them to any groups. They will appear in your Cloud site user list.
If you choose to migrate users later, their product and group access will be updated.
Also, if you choose not to migrate users and groups and you have a space permission granted by a group that don't exist in Cloud, the Confluence Cloud Migration Assistant will not migrate the respective space permission. To avoid this scenario, we recommend you to create the specific group in the Cloud site before migration.
Other things to be aware of when migrating users and groups:
We have been rolling out changes to user management that may affect your migration experience. From your organisation 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 organisation. Read more about how groups and permissions are migrated. If you have any concerns, contact support.
Users are migrated using email address as the source of truth. On subsequent migrations, the migration assistant will link users 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.
Confluence 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 Confluence 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 Confluence as a knowledge base for Jira Service Management (formerly Jira Service Desk), your Jira Service Management users may also be migrated along with your Confluence users. This will happen if you can see your Jira Service Management users in the cwd_user table in Confluence.
If you want to migrate all or some of your spaces choose Migrate spaces from the options. You will then be able to select what spaces you want to migrate. If you aren’t migrating any spaces you will be taken straight to check for errors.
Select the spaces you want to add to your migration. You can filter the list or search for particular spaces, or click Select all if you want to migrate everything at once. You won’t be able to migrate spaces with space keys that already exist in your Confluence Cloud destination site.
If a space has a MIGRATED status, we have detected that you have already migrated this space to the same cloud site.
If a space has a QUEUED status, it has already been added to a migration that is waiting to be run.
If you have lots of spaces and attachments or you are on Data Center, you might want to break the migration up into a few smaller migrations. The migration assistant can be slow to load and process tasks when there is a lot to manage.
When you've chosen all your spaces, select Add to migration.
You can choose to migrate all the apps that you marked as ‘Needed in cloud’ while assessing your apps. Or, you can choose not to migrate any apps at this stage.
3. Check for errors
In this step, the Confluence Cloud Migration Assistant will review your migration and check for common errors. It will check if:
your Migration Assistant app is up to date
users have valid and unique email addresses
groups will merge through the migration process
spaces already exist in your Cloud site
spaces are publicly available and searchable online
app assessment is complete, or you need to change your app assessment decision
you need to remove apps from this migration
You may also encounter other issues during the migration process; this step only checks for the issues mentioned here.
The table below explains what the symbol next to each listed message means.
A green tick means that the check has passed.
Proceed to the next step in your migration.
A yellow warning means that you can continue, but you need to be aware of a potential issue.
Expand the error and warning messages to reveal more details and links.
A red error means that you need to resolve the error before you can run your migration.
Expand the error and warning messages to reveal more details and links.
Understand the ‘Check’ messages
System: The table below lists errors and warning messages related to the Confluence Cloud Migration Assistant version.
The Migration Assistant is not up to date
This message indicates that the version of the Cloud Migration Assistant that you’re using is out of date.
Update to the latest supported version of the Cloud Migration Assistant.
Users and groups errors
All users will need to have a valid and unique email address. If we detect invalid emails or multiple users with the same email, you will get an error. You will need to fix these email addresses before you can run your migration.
If you have chosen to migrate all users, we will check to see if you have any groups with the same name already in your Cloud site. If we find groups with the same name, we will merge the users from the Server group into the Cloud group with the same name. You can continue with your migration without fixing this issue, but it’s important to check that this won’t cause permission escalation.
The following groups manage admin access and are blocklisted. They will not be migrated at all: "site-admins", "system-administrators", "atlassian-addons", "atlassian-addons-admin". Users in these groups will still be migrated; if you want them to be in one of the blocklisted groups you’ll need to manually add them after migration.
If you’re migrating spaces we will check to see if there will be any space key conflicts. If you get an error you can:
choose not to migrate these spaces by removing them from your migration
You will need to resolve any space key conflicts before you can run your migration.
The table below lists errors and warning messages related to apps.
App assessment is incomplete
You will be taken back to the app assessment table. You should assign statuses to each of the apps in your assessment. Once the table is completed, rerunning the check will display a green tick.
Some apps marked as 'Needed in cloud' on your server are out of date
You will need to update your apps in server to a version that’s compatible for app migration. Contact your Marketplace Partner for information on app versions that are compatible for app migration.
You have not consented to app data migration
You need to consent to app migration on the ‘Agree’ screen.
Some 'Needed in cloud' apps are not installed on your cloud site
You need to install all the apps that you have chosen as ‘Needed in Cloud’ on your Cloud site. You can do this on the ‘Install’ screen.
Some apps marked as ‘Needed in cloud’ do not meet the migration success rate criteria
If you have selected apps marked as Stage 1 that have unknown or low migration success rates, you will be given the option to:
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.
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 dashboard. There, you can view the progress and details of all your migrations.
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, stop a migration that's currently running, 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.
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 users, groups and spaces may already have been migrated to your Confluence 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, spaces, 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 chosen entity already exists in the destination site, or the migration hit an unexpected error.
Depending on the type of migration, there may be some things you need to do once your migration is finished.
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 Review imported groups. (If you have the Free plan, permissions can’t be modified; users and groups retain the same permissions that they had on your original site.)
Add users to the generic 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.
After migrating spaces, it may take a while for them to appear in the space directory. However, you can still access them via a direct link.
To check that your spaces have migrated successfully:
Review content and spaces, or ask your users to review their own content.
Check for any instances of Former User. This means that we were unable to match content to a user.
Link your other Atlassian products by going to Settings > Application links.
Use the Jira macro repair to update any links to Jira. On your Cloud site go to Settings > Jira macro repair and follow the steps.
Confluence short links like https://confluence.example.com/x/PywS may not work after migrating. Replacing them with internal links (or full URLs if they’re not in your Confluence site) before migrating should solve this issue.
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. Please 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.
You can also perform the following additional actions:
install any apps you wish to use and onboard your users.
For the full overview of post-migration actions check out the Cloud migration guide.
More information and support
We have a number of channels available to help you with your migration.
for migration planning information, go to the Atlassian Migration Program website
for technical issues or 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.
Was this helpful?