Plan your Cloud migration
Documents to help you prepare to migrate your Atlassian Server products.
Use the Bitbucket Cloud Migration Assistant to migrate
Download and install the Bitbucket Cloud Migration Assistant
For more information on planning your migration to Bitbucket Cloud, refer to Plan your Bitbucket Server to cloud migration.
What gets migrated today and the roadmap
For more details on what is and is not migrated using the Bitbucket Cloud Migration Assistant, check out What gets migrated with Bitbucket Cloud Migration Assistant.
To stay informed about the work being done on the migration assistant, keep an eye on our cloud migration roadmap.
The Bitbucket Cloud Migration Assistant is an app that helps you move repositories and pull requests from Bitbucket Server to the cloud. Any active users in your Bitbucket Server instance are also migrated to your Bitbucket Cloud workspace, where you can go to access them and provide the proper permissions and settings across your workflows.
Built and maintained by Atlassian, the Bitbucket Cloud Migration Assistant is free to install and use. The latest version of the migration assistant can be accessed in the Atlassian Marketplace. You must be using version 7.0 or later of Bitbucket Server to install and use the Bitbucket Cloud Migration Assistant.
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 your Bitbucket Server instance is behind a firewall, you’ll need to allow access to the domain: atlassian.com.
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.
You should only run one migration at a time. There is a known issue where running multiple migrations simultaneously can cause the migration to fail.
Read and review the How it works page to get a better understanding of what it takes to migrate your server instance to the cloud. There are five key steps to set up and run your migration from server to cloud. Once you have reviewed those steps, select the Connect to cloud button to get started.
Connect to cloud
Add a name for your cloud migration plan.
Select Choose cloud destination to add your cloud destination workspace to your migration plan.
If you’ve already started a cloud migration or have saved a migration you are coming back to complete, select the Choose workspace dropdown and select your cloud destination workspace from the list and select Next.
Select Create a free Bitbucket account if you do not already have a Bitbucket Cloud account.
Select Continue in the Choose your cloud destination modal that is displayed. This will take you to a new page where you will enter your existing Bitbucket Server base URL and new cloud destination.
Find your Bitbucket Server Base URL: select Administration> select Server settings under System on the Administration navigation bar > copy the Base URL under Server settings.
Add your Bitbucket Server Base URL in the Migration from text field.
Select the Choose workspace dropdown under Migrate to and select the workspace you want to migrate to from your Server instance.
Select the Allow Atlassian to access migration data checkbox.
Select Confirm.
You will need to create a new Workspace or use one that was created as opposed to using a workspace named after your own user account (created automatically for each user in Bitbucket Cloud) as the default workspace has limited functionality.
Renaming a default workspace does not convert it into a full team/shared workspace.
Choose what to migrate
Migrate your users and choose the repositories you’d like to migrate to Bitbucket Cloud.
Migrating users
Your Server users will be added to the Bitbucket Migration Users group in Bitbucket Cloud. Note: The migrated users will not have access to anything within Bitbucket Cloud. You will need to create groups or move them to existing groups and provide the migrated users the necessary access and permissions to any repositories or other content in Bitbucket Cloud.
Select Choose repositories to move onto the next step in the cloud migration process.
Choose the repositories you’d like to migrate
Select the repositories you would like to migrate to your cloud destination.
Select Add to migration once you have selected all the repositories and projects to be migrated to your cloud destination.
You can search and filter by repositories and/or projects to help make your list more manageable, such as grouping your repositories by project.
If a project with the same name does not exist in Bitbucket Cloud, then a project with that name will be created in your cloud destination and your repositories will be migrated into that new project.
If a project with the same name does exist in Bitbucket Cloud, then we will migrate your repositories into that existing project in your cloud destination.
Pull request data migration
Comments and tasks are migrated to your new cloud destination but may not display as expected, meaning previously nested comments and tasks will be flattened in both the main body of the pull request and the right sidebar.
Also, if you don’t see some comments after migrating to the cloud, check the outdated comments for that pull request.
Check for errors
To begin this step, the Bitbucket Cloud Migration Assistant will review your migration and check for some common errors.
The Bitbucket Cloud migration assistant checks for the following errors:
Ensure you are running the latest version of the migration assistant
Ensure all your active users have a unique and valid email address
Ensure all projects contain valid information, such as character limits and formatting or the length of the description
Ensure the repositories all still exist in the Server instance
Ensure all the repositories are within the Bitbucket Cloud repository size limit
Ensure all the repositories contain valid information, such as duplicates or character limits on names and slugs or formatting issues
Error message statuses
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.
Actions you can take
Review migration - select if you are ready to migrate, knowing that there may be some warning-level errors that still exist but are not blocking your migration
Save - you can save your migration and come back to it later, maybe after you have taken the time to fix any blockers or you just have more time to complete the actual migration
Refresh all - after removing blockers or fixing errors, you can ‘refresh’ the page to check for any outstanding or remaining errors before continuing to review your migration
Review your migration
This is the last step before you run the migration you have set up using the Bitbucket Cloud Migration Assistant. If you still have outstanding errors, but they are only warnings and not blockers, you can still run your migration but there may be issues. It is best practice to ensure you have fixed or alleviated any existing errors prior to running your migration to your cloud destination.
If you have any errors that are blockers, you will not be able to access the Run button until those errors are fixed.
Fix outstanding errors
If you have fixed existing errors, you can select Refresh to reload the migration review panel. Select the View details link to see more details about any outstanding errors. This will take you back to the Checks step in the migration process where you can access and fix any existing errors.
Migrate now or later
Run your migration
If everything looks correct and you have alleviated any errors blocking your current migration, select Run to begin running your migration. As stated in the migration assistant, depending on the size of you repositories and any related data as well as your upload speed, migration could take anywhere from minutes to hours.
Save your migration
If you want or need to save your migration to run at a later time or date, select Save. This will save your migration to your migration dashboard, which you can access by going to the Administration settings in Bitbucket Server and select Migrate to cloud in the left navigation sidebar.
View migration details and access your Bitbucket Cloud workspace
After you select Run and your migration begins, you will be taken to a screen where you can view the details of your migration. You can see what repositories are explicitly being migrated by expanding the Repositories dropdown under the This migration includes heading.
You can Stop your migration while it is running, but stopping your migration means you will need to start the migration over again in the future. Anything that may have been migrated will be in your cloud workspace, so be aware of this as you start the migration again on a later date.
When you are ready to start this migration again, delete any repositories that were migrated to your cloud destination to avoid receiving ‘Invalid repository’ errors during the migration process. If the repositories have not been updated or changed in any way since your initial migration attempt, you can proceed without deleting the repositories from your cloud destination.
Success
Once your migration has completed successfully, select Go to cloud workspace to access your Bitbucket Cloud workspace containing your migrated data.
Success with errors
Your migration can be completed and still return some errors. Select Go to cloud workspace to check your cloud workspace and see what was migrated successfully. From this point, you can either start a new migration or download a ZIP file of your current instance in Server and contact our support team.
Failed migration
If your migration fails, either create a new migration that avoids the errors, or create a ZIP file of your Server instance and contact our support team.
Congrats! You’ve migrated to Bitbucket Cloud. Check out After migrating to Bitbucket Cloud to get started.
More information and support
We have a number of channels available to help you with your migration.
Our Bitbucket Cloud support team can help with technical questions or issues related to your migration.
For help with a large-scale migration, we also have a wide network of partners globally that are experienced in Atlassian migrations. Get in touch to find one who can help with your migration.
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?