• Products
  • Documentation
  • Resources

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

At this time, only the following will be migrated to the cloud:

  • Repository Git information - If your repository is part of a project in Server, the repository will be migrated to a new project with the Server project name or added to a project of the same name that already exists in your cloud destination. Note: At this time, we do not support migrating forked repositories. Merge any open pull requests from forks to prevent any data corruption prior to migrating to the cloud.

  • Pull request information - Title, description, pull request status (open, merged, declined), and the code diff, comments, tasks, and authors/reviewers.

  • Users - All active or licensed users and any inactive users who are attached to a pull request (are a owner/author or reviewer) in your Server instance will be migrated to Bitbucket Cloud.

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

  1. Add a name for your cloud migration plan.

  2. Select Choose cloud destination to add your cloud destination workspace to your migration plan.

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

    2. Select Create a free Bitbucket account if you do not already have a Bitbucket Cloud account.

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

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

  5. Add your Bitbucket Server Base URL in the Migration from text field.

  6. Select the Choose workspace dropdown under Migrate to and select the workspace you want to migrate to from your Server instance.

  7. Select the Allow Atlassian to access migration data checkbox.

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

  1. Select the repositories you would like to migrate to your cloud destination.

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

bitbucket cloud migration preflight checks pass

If you get a warning sign then you can continue, but you need to be aware of a potential issue.

bitbucket cloud migration preflight checks warning

If a check comes back with a red error, then you will need to resolve the error before you can run your migration.

bitbucket cloud migration preflight checks fail

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 the post migration documentation to get started.

Last modified on Nov 16, 2021
Cached at 11:28 AM on Dec 2, 2021 |

Additional Help