Use the Bitbucket Cloud Migration Assistant to migrate
Before you begin
You will need to create a Bitbucket Cloud account in order to migrate from your Server or Data Center instance to the cloud.
Create a workspace: We recommend creating your workspace in Atlassian Administration, and if you already use Jira or Confluence, you can add Bitbucket to your current Atlassian organization at admin.atlassian.com. For more information on creating a workspace, refer to Join or create a workspace.
Start a free Bitbucket Cloud migration trial: New to Bitbucket? Want to test out the app as well as your cloud migration strategy? Create a Bitbucket Cloud migration trial. For more information on how cloud migration trials work, check out Cloud migration trials for Server and Data Center customers.
Note: If you are migrating, you will need a Standard or Premium plan. Learn more about plans and billing.
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.
Download and install the Bitbucket Cloud Migration Assistant
The Bitbucket Cloud Migration Assistant is a tool 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 I already have a workspace to add your cloud destination workspace to your migration plan.
If you’ve already connected a workspace to the Bitbucket Cloud Migration Assistant, select the Choose workspace dropdown and select your cloud destination workspace from the list and select Next.
New to Bitbucket Cloud? Select Get Bitbucket Cloud trial to start a Bitbucket Cloud migration trialand become more familiar with Bitbucket and cloud migration. We recommend that you create your workspace in Atlassian Administration, which, if you already use Jira and/or Confluence, will add Bitbucket Cloud to your existing organization. Follow the steps in the Join or create a workspace help doc.
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.
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.
Migrate branch permissions and branching models
Atlassian administrated workspaces only
Groups can only be migrated to workspaces that are within your organization in Atlassian Administration at admin.atlassian.com. To learn more about adding Bitbucket to your Atlassian organization, refer to Add a new cloud app to your organization.
Option | Description |
|---|---|
Migrate branch permissions and branching models | Migrate branch permissions and branching models from Bitbucket Server to Cloud. Note: Inactive users will be migrated to the cloud with no permissions or branching models associated to them. |
Do not migrate branch permissions and branching models | Do not migrate branch permissions and branching models from Server to Cloud. |
What gets migrated and how it affects the migration of users and groups
If you are migrating your branch permissions from Server, any users and groups that are referenced in your branch permissions in Server and are not included in those you choose to migrate will be migrated to the cloud, but if you do not choose to migrate groups, then any groups not in the cloud will be filtered out of the migration.
What does not get migrated?
Permissions and any associated branching models in Server are not migrated with inactive users from Server to Cloud. The inactive user will be migrated to your cloud workspace with none of the permissions and no association with any branching models that were set up on Server or Data Center.
Migrating users
Choose which users to migrate
Option | Description |
|---|---|
All users | Migrate all users from Bitbucket Server to Cloud. |
Only users who have access to or have been involved in any pull requests within the selected repositories | Migrate users who have been involved in any pull requests within or currently have at least read access to the repositories that were selected for migrations |
Only users who have been involved in any pull requests within the selected repositories | Migrate users who have been involved in any pull requests within the repositories selected for migration |
Migrate users with invalid email addresses as inactive users | Any users who have an invalid email address upon migrating to the cloud will be migrated as an inactive Bitbucket user. |
Migrating groups
Atlassian administrated workspaces only
Groups can only be migrated to workspaces that are within your organization in Atlassian Administration at admin.atlassian.com. To learn more about adding Bitbucket to your Atlassian organization, refer to Add a new product to your organization.
Choose what groups to migrate
Option | Description |
|---|---|
All groups | All groups on your Server instance will be migrated to Cloud, if you have groups with the same name in Bitbucket Cloud, we will add the corresponding users to that group. Any groups not already on cloud will be created, and all users will be added to these groups. |
Only groups with users and permissions selected for migration | If you’ve chosen either to migrate only users who have access to or have been involved in pull requests in the repositories you’ve selected to migrate then the following is true. Depending on the repositories and users you have selected migrate, only groups that satisfy both the following conditions will be migrated to the cloud:
|
This applies to both of the above scenarios | If groups with the same name already exist, any users will be migrated into the existing group on cloud with that name. For example, ‘Group1' exists on both Bitbucket Server and Cloud. On server, ‘User1’ and ‘User2’ are in ‘Group1’, and on cloud, ‘User2’ and ‘User3’ are in ‘Group1’. When you migrate, ‘Group1’ on cloud will now have all three users (User1, User2, and User3). Note: This could mean that some users are given access to products or features they did not have access to before. |
Do not migrate any groups | No groups will be migrated. You should consider this option if you are currently syncing users and groups with a third-party identity provider (IDP). Note: If you’ve already synced your users and groups using an IDP and want to migrate your permissions to the cloud, select Do not migrate groups and Migrate permissions for all users and groups |
Migrating permissions
Atlassian administrated workspaces only
Permissions can only be migrated to workspaces that are within your organization in Atlassian Administration at admin.atlassian.com. To learn more about adding Bitbucket to your Atlassian organization, refer to Add a new cloud app to your organization.
Choose which permissions to migrate
Option | Description |
|---|---|
Migrate permissions for all users and groups | Migrate all user and group permissions from Bitbucket Server to Cloud, including global permissions and those specific to selected repositories or parent projects, for the users and groups included in the migration. If you choose Do not migrate any groups, we will identify the groups that would have been migrated from your Server instance and migrate permissions for any groups that already existing in Cloud with the same name as the group in Server. |
Do not migrate any permissions | No permissions will be migrated to the cloud |
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 you are on either a Standard or Premium Bitbucket plan
Check to see if you have a workspace in Atlassian Administration
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?