• Products
  • Documentation
  • Resources

Plan your Bitbucket Server to cloud migration


This guide provides an overview of recommended activities before and during the cloud migration process. It covers enlisting your team, evaluating technology options, ensuring that the current Bitbucket Server site is ready for migration, and executing the migration. 

Not ready to start planning your migration? Learn more about cloud migration or check out our cloud roadmap.

Important changes to our server and Data Center products

We’ve ended sales for new server licenses, and will end support for server on February 2, 2024. We’re continuing our investment in Data Center with several key improvements. Learn what this means for you

Who should use this guide?

Use this guide when:

  • You want to evaluate if you should migrate from Bitbucket Server to Bitbucket Cloud.

  • You've decided you want to, and need to know how to plan and conduct the migration.

Looking to migrate to Jira or Confluence Cloud as well? Check out the Jira server to cloud migration resources or the Confluence server to cloud migration resources for more details


  1. Know what you can migrate: Currently, we support migrating the following with the Bitbucket Migration Assistant:

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

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

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

  2. Review your security and compliance requirements: Adhering to your organization's security requirements is critical to a successful migration. For more information about Atlassian's security, privacy, and compliance policies, check out Trust at Atlassian. At this point, you may want to work with your procurement or security teams to make sure Bitbucket Cloud meets your requirements.

  3. Evaluate apps: Before deciding to migrate, review any apps and custom integrations you may have to determine what you'll need for your Bitbucket Cloud site. The Atlassian Marketplace offers a variety of apps and integrations that extend the functionality of Bitbucket Cloud. These include free integrations with leading SaaS productivity and collaboration products like Slack and Gmail, and subscription-based licensing of some of your most beloved server apps. Keep in mind while you're evaluating that while Atlassian’s cloud and server products provide the same benefits, they can differ in features and functionality. As you evaluate, you may discover that Bitbucket Cloud includes functionality that is fulfilled through an app on server. Refer to Functional differences in Bitbucket Cloud for more information. You may also have in-house or custom-built apps to consider. 

    1. App data is not typically included when migrating from Bitbucket Server to Bitbucket Cloud. Some apps do have the capability to export and import their data but you'll need to check with the app developers or their documentation to confirm if this is possible.

    2.  If you do need to map Bitbucket Server apps to Bitbucket Cloud, first check if there is a cloud equivalent of your server app in our Marketplace. If there is a cloud equivalent, your next step would be to check with the app developer to see if it stores any data. If it does, you'll need to work with the app vendor to understand your data migration options. Atlassian doesn't directly handle migrating data generated from third-party server apps to cloud apps. If there's no equivalent and the app stores data, you should still contact the vendor to see if there's a way to export the data. 

  4. Check costs: There's no cost to migrate to Bitbucket Cloud besides the cost of your Bitbucket Cloud subscription. However, you'll still want to assess your payment options and overall costs. A few things to keep in mind:

    1. Unlike Bitbucket Server, Bitbucket Cloud is offered as a monthly subscription on a per-user basis, with three different pricing plans: Free, Standard, and Premium. Check out Bitbucket Licensing to decide which plan is best for your team and estimate your monthly costs.

    2. If you're planning on using apps from the Atlassian Marketplace in Bitbucket Cloud, remember to factor these into your cost considerations.

    3. Note that your existing Bitbucket Server license and maintenance won't transfer to Bitbucket Cloud. These are two separate licenses and are paid for separately.

  5. Try out Bitbucket Cloud: Sign up for a free Bitbucket Cloud trial to give Bitbucket Cloud a spin. Keep in mind as you try it out that the design and user interface and administration experience can vary across Bitbucket Server and Bitbucket Cloud, and you can't switch between the two. We recommend trying cloud before migrating to get comfortable with the differences and identify any communications or training needed to help onboard your users.

Prepare to migrate

Now that you've decided to migrate, let's figure out how to get you there.

  1. Assemble your team: Migrating from Bitbucket Server to Cloud will have an impact on your users' experience and workflows, as well as various stakeholders throughout your organization. Depending on the size of your organization and number of users, a migration may require a fully fledged project with defined roles and responsibilities across teams. As early as possible, you should communicate with individuals and stakeholders who are interested and impacted by a move to Bitbucket Cloud. Where possible, recruit and enlist these people to be a part of the process.

  2. Communicate early and often: Beyond informing your organization about the migration schedule, share your migration plan with team members. Determine how you'll alert users about any issues or errors that arise. At this stage, your migration communication plan should cover things like:

    1. When will the migration occur?

    2. What downtime can users expect?

    3. Ask people to avoid changing anything during the transition.

    4. What will happen to the old site after migrating? Will it still be accessible or readable?

  3. Prepare your Bitbucket Server: Evaluate your current environment to determine if you need to make any changes before migrating your data. We recommend finishing and merging or closing all open pull requests before migrating. This way, all new pull requests will get created directly in Bitbucket Cloud after you migrate. Also, go through your server user base and clean up any users who may be inactive or don’t need to be migrated to your new cloud destination. Note: In Server, you can have multiple repositories with the same name or slug, but in Bitbucket Cloud each repository name and slug needs to be unique. To avoid any issues, ensure that the name and slug of your repositories is unique throughout your Server instance before migrating to the cloud.

  4. Set up your organization: An organization allows you to view all Atlassian cloud users at your company in one place, manage your users' accounts, and set up security features like SAML SSO. Organizations are particularly helpful if your company manages more than one Atlassian cloud site and wants insight into all your sites, products, and the users who can access them. Learn more about how to set up an organization.

  5. Evaluate authentication options: Bitbucket Cloud supports SAML SSO with a subscription to Atlassian Access. You can configure SAML SSO for all users in your organization. When they access the Bitbucket Cloud web interface, they will be redirected to your SSO provider to log in. However, your users' SSO credentials are not valid for Git operations. Users will need to use an app password for https authentication, or switch to SSH authentication for Git operations.

  6. User migration: If you are using the Bitbucket Cloud Migration Assistant, 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. Note: If you are using any of the other migration methods mentioned in Step 1 of the Migration section, only repositories will be migrated to the cloud.

Additional considerations

  • Migration services: If you need assistance with your migration, we have a wide network of partners globally that are very experienced in Atlassian migrations. Visit our Atlassian Partners contact form to find one who can help with your migration.


After you have the necessary prerequisites in place and have completed the tasks associated with the pre-migration phase, you're ready to perform the migration. The steps outlined below provide guidance around migrating from your server instance to your new cloud destination.

At this time, the recommended way to migrate to Bitbucket Cloud is using the Bitbucket Cloud Migration Assistant as listed below in our migration methods. Refer to the following guide to learn how to migrate to the cloud using the migration assistant: Use the Bitbucket Cloud Migration Assistant to migrate.

  1. Choose a migration method: There are a few ways to move your data to the cloud:

    1. Recommended: Download and use the Bitbucket Cloud Migration Assistant from the Atlassian Marketplace. For more information on using the migration assistant, refer to our Use the Bitbucket Cloud Migration Assistant to migrate help documentation.

    2. Use our repository importer to import individual repositories. To migrate using the importer, your Bitbucket Server domain needs to be publicly accessible. If it's not publicly accessible Bitbucket Cloud will not be able to access to your Bitbucket Server to perform the import.

    3. You can also create a new repository on Bitbucket Cloud, and then simply push from your local repository to the new repository in Bitbucket Cloud.

    4. If you have a lot of repositories, Bitbucket Cloud provides APIs for you to script the creation and pushing of repositories in bulk.

  2. Run a test migration: We recommend performing a trial run in a testing or staging site to ensure that everything is working expected and the migration runs smoothly. You can do this using a free Bitbucket Cloud trial. The test migration will help you:

    1. Identify possible bugs and the steps needed to resolve before the actual migration.

    2. Establish a clearer timeline for your live migration, including any expected downtime.

    3. Validate the data before moving to Bitbucket Cloud.

  3. Build a timeline: Identifying an ideal migration window can mean the difference between happy and frustrated users. Determine how much time your migration will take, factoring in time for troubleshooting. Consider scheduling the migration for overnight, on a weekend, or when your team is less likely to need access to Bitbucket. This will reduce the risk of data discrepancies between server and cloud.

  4. Migrate to cloud: Run your production migration using your chosen migration method. Don't forget to lock down your server or remind your users not to make changes during the migration window. You will probably need to spend some time testing and troubleshooting before you can safely invite your users to cloud. 

Common scenarios

Not all migrations are quite so straightforward. Below are some of the common migration scenarios you may encounter, and guidance on how to approach each.

  • Merging server sites: If you are using the repository importer and you need to merge multiple server sites, just follow the same process for each site to import your repositories and add your users to your cloud site.

Troubleshooting your migration

If you've run into a problem during your migration, we're here to help. You can start by searching for known issues in Bitbucket Server or Bitbucket Cloud in our public issue trackers. There, you can find information about some of the common issues we see with Bitbucket migrations, including their status and suggested workarounds.

If you've run into a different question or need help to move forward with your migration, you can contact the Bitbucket Cloud Support team or reach out to our Atlassian Community for advice.

After migrating

After you've successfully completed the migration, you'll need to go through a series of post-migration tasks to ensure that everything is functioning as smoothly and efficiently as possible.

  • Review your cloud site: When your migration is complete, you will need to review the new Bitbucket Cloud site to ensure your data has migrated successfully. We recommend:

    • Checking repositories for things like your commits and branches.

    • Allowing time for different teams and users to test different functionality.

    • Testing the operation and functionality of the application to identify any behavior gaps and, if needed, document them for your users. 

  • User permissions: Once you have migrated to Bitbucket Cloud, you will need to create the necessary groups, assign members to these groups, and set the permissions for those groups to access any repositories. We are working on migrating user permissions to Bitbucket Cloud in a future release. For more information, see the Bitbucket Cloud migration roadmap. For more details on how to query a list of all the permissions and users in your current Server instance, see the following support document: List all permissions and users of Repositories in Bitbucket | Bitbucket Data Center and Server | Atlassian Documentation

  • Project settings and permissions: We are currently working on creating more parity between projects in our Server (and Data Center) products and Bitbucket Cloud. Check out the Bitbucket Cloud roadmap for more information on release dates and timing for project settings and permissions to be available in Bitbucket Cloud.

  • Default reviewers: You will need to manually add your default reviewers from Server over to your new cloud destination. For more information on when default reviewers will be migrated, see the Bitbucket Cloud roadmap.

  • Branch permissions: Once you have migrated to the cloud, you will need to set up your branch permissions to match what you had set up in Server. For more information on using branch permissions in Bitbucket Cloud, refer to the User branch permissions support document.

  • Webhooks: Webhooks will not be migrated to Bitbucket Cloud using the migration assistant, and this feature is not currently on the Bitbucket Cloud roadmap. Learn more about managing webhooks in Bitbucket Cloud.

  • Merge checks: You will need to suggest or enforce merge checks across your repositories in your new cloud destination. For more understanding around merge checks in Bitbucket Cloud, refer to the Suggest or require checks before a merge support document.

  • Connecting your Bitbucket Cloud workspace to Jira Software: Having your commits, branches, pull-requests, builds and deploys reported into Jira brings a massive amount of visibility into your development flow. As you have just migrated from Bitbucket Server, you should be familiar with this value and want to connect your Bitbucket Cloud workspace to your Jira instance.

  • Install apps: If you've identified apps that should be installed, add them to your Bitbucket Cloud site.

  • Get acquainted with cloud: To learn more about what's new in Bitbucket Cloud and how to get the most of it, check out the Bitbucket Cloud documentation. Consider sharing this resource with your users if this is their first introduction to Bitbucket Cloud. You may also find the Atlassian Cloud documentation a helpful resource as you get started as a Bitbucket Cloud admin.

  • Welcome your team: Now that the migration is complete, make sure your organization is ready. We recommend developing a comprehensive launch communication plan to share the new Bitbucket Cloud site information with the team. This can cover topics like:

    • What action is needed post-migration? For example:

      • Resetting passwords

      • Resetting avatars

      • Updating local remote URLs for migrated repositories

    • What URL will they use to access the new site?

    • Who can they contact with questions, and how? For example, can you provide a chat room or an issue tracker where people can raise any issues or feedback?

    • Are there any notable changes they'll need to be aware of?

    • Links to any further reading or FAQs.

Sit back and relax

Now that you're a cloud admin, you'll have immediate access to our latest features and bug fixes. Installs, upgrades, and patches are managed seamlessly by Atlassian, so you can relax on your weekends. 

To keep track of major changes that affect all users of the Bitbucket Cloud products, follow the Atlassian Cloud Documentation blog. This includes new features, bug fixes, and other changes across all Atlassian cloud products. You can also take a look at our Bitbucket Cloud general enhancements roadmap to stay informed about the latest features coming to Bitbucket Cloud.

More information and support

We have a number of channels available to help you with your migration.

  • Get an inside view on the latest features and improvements to the Bitbucket Cloud Migration Assistant by checking out the Migration to Bitbucket Server roadmap.

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

Additional Help