Your Bitbucket Cloud Migration Playbook

Migrating your Bitbucket repositories from a self-hosted server or Data Center to Bitbucket Cloud is a significant step for any IT team. After Atlassian ended support for Bitbucket Server in 2024, organizations looking to embrace the benefits of the cloud found that a well-planned migration was essential. However, moving code, pull requests, and CI/CD pipelines to the cloud can be complex. A successful migration requires careful preparation, the right tools, and a clear strategy to avoid downtime or data loss.

This playbook provides a step-by-step guide for IT teams planning a Bitbucket Cloud migration from thorough preparation through execution. We’ll walk through key steps like assessing your current repositories and projects, using the Bitbucket Cloud Migration Assistant, and handling special cases that could impact the move. Throughout, you’ll find best practices and a handy checklist to minimize downtime and ensure a smooth transition. By following this guide, you can confidently migrate to Bitbucket Cloud while keeping your development workflow running smoothly.

Assess Your Current Bitbucket Environment

Before diving into any migration, take time to evaluate and tidy up your existing Bitbucket Server/Data Center environment. A thorough assessment helps uncover potential issues early and sets the stage for a smoother transition. Key areas to assess include:

• Inventory all repositories and projects: List out every project and repository in your Bitbucket instance. Identify which repositories need to move to the cloud. Consider archiving or deleting outdated, inactive, or test repositories to streamline the migration. A smaller, well-organized set of repos will be easier to migrate and manage in the cloud.

• Review repository settings and size: Check each repository’s size and contents. If you have extremely large repositories or use Git Large File Storage (LFS) for large binaries, note this for migration planning. Ensure repository names and URLs are unique, as Bitbucket Cloud requires unique repo names across a workspace.

• Identify forked repositories: If you have forked repositories, plan to handle them before migrating. Bitbucket Cloud migration currently does not support forks. It’s best to merge any open pull requests from forked repos back into the main repository or otherwise reconcile them. This prevents data loss since fork relationships won’t carry over to cloud.

• Examine pull requests and branches: Take stock of open pull requests and long-lived branches. Aim to merge or close out as many open pull requests as possible before migrating. This ensures those changes are resolved in your source environment so that the cloud starts fresh with only active work. It also reduces the chance of confusion or divergence after migration.

• Evaluate user accounts and groups: Review your user list and access groups in Bitbucket. Clean up any users who are no longer active or needed. This will simplify migrating your user base to Atlassian Cloud and avoid paying for inactive accounts. Note which groups and permissions structures you have, as you may want to replicate these in the cloud or take the opportunity to simplify access control.

• Audit apps and integrations: Catalog any Bitbucket Marketplace apps, custom add-ons, or integrations that your server instance uses. Many server apps may not have direct equivalents in Bitbucket Cloud, or their data might not migrate automatically. Identifying these now allows you to find cloud alternatives or plan to manually reconfigure critical integrations post-migration.

• Assess CI/CD connections: Document how your Bitbucket instance ties into Continuous Integration/Continuous Deployment. If you’re running Bamboo or another CI tool connected to Bitbucket, note this Bitbucket Cloud doesn’t support Atlassian’s Bamboo server product. You’ll need to plan for a CI/CD solution in the cloud. Understanding your current build pipeline setup is crucial for a seamless switch to cloud-based pipelines.

By auditing your current environment with the above steps, you’ll have a clear picture of what needs to be moved and what preparatory work should be done. This upfront housekeeping reduces surprises later and forms the foundation of your migration plan.

Plan and Prepare Your Migration Strategy

With a solid grasp of your current setup, the next step is to develop a comprehensive migration plan. Treat the migration as a project with defined phases, resources, and timelines. Planning thoroughly will minimize risks and keep everyone aligned. Key planning considerations include:

Assemble a cross-functional team: Bring together a project team for the migration that includes Bitbucket administrators, IT operations staff, and representatives of development teams using Bitbucket. Assign clear roles and responsibilities such as who will run the migration tool, who will handle communication, and who will verify data afterwards. If your organization is large, you may even form a formal project group to manage this transition. Early involvement of stakeholders ensures you have buy-in and expertise for each aspect of the move.

Define scope and timeline: Decide which repositories are in scope for the cloud migration and which might be left behind or archived. Create a timeline that includes key milestones: completing pre-migration cleanup tasks, running a test migration, freezing changes on the source system, performing the production migration, and post-migration validation. Be realistic about how long each step will take. If you have hundreds of repositories or very large data sets, buffer extra time. Whenever possible, schedule the final cutover during off-peak hours to minimize impact on developers.

Set up your Bitbucket Cloud environment: Prepare the target cloud instance in advance. This means creating a Bitbucket Cloud workspace under your company’s Atlassian Cloud account. Ensure you have the appropriate subscription level for your user count and needs for example, Bitbucket Cloud’s Free plan only allows up to 5 users, so larger teams will require a Standard or Premium plan. It’s wise to start with a free cloud trial or a test workspace to get familiar with Cloud’s interface and features. This trial environment can also be used for a dry-run migration to flush out any issues. Make sure to invite any key admins to the workspace and configure baseline settings ahead of time.

Communicate with your users: Create a communication plan to keep developers and stakeholders informed at each stage. Well before the migration date, announce the intention to migrate to Bitbucket Cloud and highlight any benefits. As the date approaches, notify users of the expected downtime or read-only period when the migration will occur. It’s critical that everyone knows, for example, “On Friday at 6 PM we will freeze the Bitbucket Server for migration. Please do not push any new commits or create pull requests after this time until we give the all-clear.” Also communicate what will happen with the old system will it be deprecated entirely, or left accessible in read-only mode for reference? Setting these expectations early helps avoid confusion or lost work during the transition.

Address compliance and security requirements: In the planning phase, involve your security and compliance teams to review the move to cloud. Verify that Bitbucket Cloud meets any regulatory requirements your code and data are subject to. Atlassian provides a Trust Center with details on cloud security measures share this with your security stakeholders. If your company uses SAML single sign-on or has specific password policies, plan to integrate Atlassian Access or configure the cloud authentication to align with your enterprise standards. It’s better to sort out SSO, user provisioning, and access controls before migrating users, so that once in cloud, your team can log in and access resources seamlessly.

Plan for training and differences: Recognize that there will be differences in how teams use Bitbucket Cloud compared to the server. During planning, identify any significant changes that users should be aware of for example, the new interface layout, or the use of Bitbucket Pipelines for CI builds instead of Bamboo. Plan to provide training materials or briefings on these changes. Perhaps schedule a demo of Bitbucket Cloud for the development team, or prepare documentation on how to run builds in the new system. Proactively addressing the human side of the migration will help your team adapt quickly and reduce downtime due to confusion.

Finally, consider performing a test migration in a non-production setting. Atlassian offers trial licenses and cloud sandbox environments that you can use to do a dry run. In a test migration, you would attempt to migrate a subset of data to the cloud to see how long it takes and what issues arise. This practice run helps validate your process, tools, and timing. It’s much better to discover and solve problems in a rehearsal than during the real migration. Use the learnings from testing to adjust your timeline and communicate any new instructions to users.

By carefully planning the who, what, when, and how of your Bitbucket Cloud migration, you set the stage for success. The project plan will serve as your guide and give confidence to everyone involved that nothing important will fall through the cracks.

Use the Bitbucket Cloud Migration Assistant

Atlassian’s Bitbucket Cloud Migration Assistant is the primary tool to execute the migration of data from Bitbucket Server/Data Center to the cloud. This free app automates much of the heavy lifting, ensuring your repositories, pull requests, and other data make it over intact. Using the Migration Assistant typically involves the following steps:

• Prepare the source and target: First, ensure your Bitbucket Server is on a supported version so that the Migration Assistant can run. Install or enable the Bitbucket Cloud Migration Assistant plugin on your server instance if it isn’t already present. On the cloud side, make sure you have your Bitbucket Cloud workspace created and that you have admin access to it.

• Launch the Migration Assistant: In your Bitbucket Server administration console, find the Migration Assistant and start a migration. The tool will prompt you to connect to your Bitbucket Cloud. You’ll log in with your Atlassian Cloud credentials and select the cloud workspace that will be the destination. Once connected, the assistant establishes a secure link between your on-premises Bitbucket and the cloud.

• Select repositories to migrate: Next, choose which repositories you want to migrate. You can migrate all repositories from a project or individual ones. The assistant will list your Bitbucket Server projects and repos so you can pick the content that should go to cloud. This is where your earlier inventory comes in handy you might exclude repos that you cleaned up or don’t need anymore.

• Choose users and groups: Bitbucket Cloud Migration Assistant allows you to bring over users and groups associated with the repositories you’re migrating. You can opt to migrate all users from your server instance or only users who have access to the selected repositories. Similarly, choose whether to migrate groups and their permissions. If you already set up some users in the cloud workspace, the assistant can map existing accounts to the migrated data. You’ll want to ensure that every repository has an owner in the cloud and that critical groups are moved over for permission consistency.

• Map or migrate permissions: During the migration config, you’ll also decide how to handle repository and project permissions. The assistant can copy over your existing permission schemes, so that things like read/write access for each repo remain the same on cloud. Alternatively, you might choose to set permissions afresh in cloud. Often it’s simplest to migrate permissions to maintain continuity, then adjust later if needed.

• Run pre-migration checks: Before performing the actual migration, the assistant will run validations to catch anything that might fail. Review any warnings or errors it reports. Common issues might include repository name conflicts, forked repositories that won’t be migrated, or users with email conflicts. Resolve any issues flagged for example, rename duplicate repositories or merge those forked pull requests we discussed earlier. Ensuring a clean bill of health here will make the live migration go much smoother.

• Start the migration: Once everything is selected and validated, you can begin the migration process. The Migration Assistant will export the chosen repositories and import them into your Bitbucket Cloud workspace. Users, groups, and permissions you opted to bring will also be created in the cloud. Depending on the volume of data, this process can take anywhere from minutes to several hours. During this time, it’s best to treat your source Bitbucket Server as read-only don’t allow new commits or changes, because they may not be included. The assistant provides progress updates as it moves through each repo.

• Verify and confirm: After the migration completes, the tool will present a summary of results, including any items that did not migrate. Take time to verify that all your repositories appear in Bitbucket Cloud with the full commit history, that pull requests and comments are present, and that users have the expected access. Spot-check a few important projects to ensure nothing is missing or corrupted. If anything failed to migrate, the assistant may log it. You can re-run a migration for specific failed pieces or contact Atlassian support if needed. In many cases, a successful run via the Migration Assistant means you’re ready to flip your team over to using Bitbucket Cloud.

Using the Bitbucket Cloud Migration Assistant streamlines what would otherwise be a very manual migration process. It is the recommended approach because it’s guided and reduces the chance of human error when transferring dozens or hundreds of repositories. By following the on-screen steps and the guidance above, you can confidently move your core data to the cloud environment. Just remember that some things are outside the scope of this tool those will be handled separately, as we’ll cover next.

Handle Special Cases and Differences

Migrating to Bitbucket Cloud isn’t only about moving repositories you also need to account for platform differences and any special cases in your environment. Two major considerations are your CI/CD pipeline tool and forked repositories:

CI/CD Pipeline Changes (Bamboo to Pipelines): Many teams using Bitbucket Server also use Atlassian’s Bamboo for continuous integration and deployment. It’s important to note that Bamboo is not available on Bitbucket Cloud. Atlassian’s cloud platform instead provides Bitbucket Pipelines, a built-in CI/CD service, as the replacement. This means that as part of your migration, you should plan how to recreate or replace your build and deployment pipelines. For example, if you have Bamboo build plans triggering from Bitbucket Server, you’ll need to convert those into Bitbucket Pipelines or find an alternate cloud CI service. Bitbucket Pipelines supports many of the same tasks but the configuration and environment will differ. Start by identifying all the Bamboo projects and plans that are tied to your Bitbucket repos. Then, for each, create an equivalent pipeline in Bitbucket Cloud: define the pipeline steps in the repo, set up necessary variables or secrets in the cloud workspace, and consider using Bitbucket Pipeline features to achieve what your Bamboo builds did. If you used advanced Bamboo features, you may need to adjust or simplify for Pipelines. Some organizations choose to use alternative CI tools integrated with Bitbucket Cloud. That’s fine too just ensure it’s all planned out so that once code is in the cloud, your team isn’t stuck without a working build system. Atlas Bench’s expertise with CI/CD transitions can help map Bamboo functionality to Bitbucket Pipelines seamlessly as well, reducing disruption in your development lifecycle.

Forked Repositories: As mentioned earlier, Bitbucket Cloud cannot automatically migrate repository forks. On Bitbucket Server, you might have allowed developers to fork repositories for experimentation or to propose changes. Those fork relationships and any open pull requests from forks will not be preserved in the migration. To avoid losing important work, plan to merge or otherwise finalize open fork pull requests before migrating. Essentially, ensure that any valuable code residing only in a fork is brought back into the main repository. Post-migration, you can still fork repositories in Bitbucket Cloud, but the history of who forked what on the old server will not carry over. If certain forks were being used like long-lived diverged copies, you may need to migrate them as independent repositories in cloud or find another strategy to include that code. It’s best to eliminate forks or incorporate their changes ahead of time to keep the migration straightforward.

Other Differences to plan for: There are a few additional differences between Bitbucket Data Center and Cloud to keep in mind. One is user management Bitbucket Cloud is tied to Atlassian accounts, so usernames might change to email-based identities, and user groups may need reconfiguration. Also, any server-level configurations might not directly transfer. For example, if you used a custom plugin on server to enforce certain merge rules, you’ll want to see if Bitbucket Cloud’s built-in merge checks can replace that, or find a Marketplace Cloud app if needed. File size limits can differ too: on server you might have raised the Git upload limits, whereas on Cloud there are fixed limits. Review Atlassian’s documentation on Bitbucket Cloud limitations so nothing catches you off guard. In short, treat the migration as not just moving data, but also transitioning to a slightly different toolset. With planning, most teams find the cloud differences are manageable or even beneficial.

Addressing these special cases and differences as part of your migration project will save you headaches later. By planning for CI/CD changes and resolving forked repo issues upfront, you’ll prevent major roadblocks. And by understanding the cloud platform’s nuances, you can make necessary adjustments proactively. Atlas Bench’s migration specialists frequently help clients navigate these exact challenges ensuring that when you flip the switch to Bitbucket Cloud, everything continues to work as expected.

Best Practices for a Smooth Migration

Even with a solid plan and the migration assistant at your disposal, there are several best practices that can significantly smooth out the process. Consider the following checklist as you prepare and execute your Bitbucket Cloud migration:

• Run a test migration in advance: If possible, do a dry run by migrating a subset of data or using a staging instance. This trial run will help uncover any unexpected issues and lets you estimate the time required more accurately. Treat it as a dress rehearsal so that your production migration is well-rehearsed.

• Backup your data before migrating: Always create a full backup or snapshot of your Bitbucket Server instance prior to the final migration. In the unlikely event something goes wrong or data is missing in the cloud, you have a safe restore point. While the goal is not to need a rollback, having backups is a critical safety net.

• Clean up and finalize open work: Before the migration day, ensure all active work is merged or saved. Close out any obsolete branches and resolve open pull requests. The cleaner your data, the less confusion there will be when users log into the new system and see only relevant, up-to-date information.

• Announce a content freeze period: For the production migration, communicate a clear “freeze” window during which the Bitbucket Server will be set to read-only. This freeze prevents diverging source and target if someone pushes a commit to the old server during migration, that commit would be missed on the cloud. It’s often best to lock repositories just before migration so it’s technically enforced. Remind the team that any changes during the freeze won’t be carried over.

• Schedule during off-hours: Plan the actual migration for a time when development activity is minimal. This might be overnight or on a weekend. Doing so minimizes the impact of the required downtime. Also, if the migration takes longer than expected, you have a buffer before the next work day starts. Factor in time for post-migration verification and potential troubleshooting in this window as well.

• Monitor the migration closely: While the Bitbucket Cloud Migration Assistant will handle the mechanics, have someone watching the process and ready to respond if an error appears. Keep logs and take screenshots or notes of any warnings. In case of a failure, you may need to retry or call Atlassian support having details will speed up resolution. It’s also good to have team members available on standby during the cutover, in case their assistance is needed.

• Verify and smoke test after migration: Once the migration completes, systematically verify that everything is working in Bitbucket Cloud. Check a sample of repositories to ensure code history, branches, and pull requests are all present. Have developers try cloning a repository from the cloud and ensure they can push and merge as expected. If you’ve set up pipelines to replace Bamboo, run a build to confirm it triggers correctly. Essentially, perform a sanity check across your key functionalities. Catching any issue immediately means it can be fixed before all users come back online.

• Provide support to users post-migration: Even with preparation, users may have questions or minor issues when they start using Bitbucket Cloud. Set up a support channel for the first few days of the transition. Common tasks include helping update remote URLs in local Git clones and re-generating any personal access tokens or app passwords for CI tools. A quick reference guide for users can be handy covering how to log in, where to find their projects, and new features they can leverage.

• Leverage expert help if needed: If your migration is complex or your team is short on time, consider engaging an Atlassian Solution Partner like Atlas Bench. Partners have extensive experience with migrations and can provide guidance or hands-on assistance. They can help audit your environment, run the migration, deal with any snags, and ensure best practices are followed. While it’s entirely possible to migrate on your own, having experts at your side can turn a high-stakes project into a predictable, low-risk procedure.

By following these best practices, you greatly increase the likelihood of a smooth migration with minimal downtime or surprises. Each step from thorough testing and backups to user communication and post-migration support contributes to an overall seamless experience. The goal is that your team transitions to Bitbucket Cloud and quickly gets back to productivity, as if little has changed.

A Smooth Journey to Bitbucket Cloud

Migrating to Bitbucket Cloud is a journey that, with the right preparation, can transform your development operations for the better. In this playbook, we covered how to assess your current Bitbucket setup, meticulously plan the migration, use Atlassian’s Bitbucket Cloud Migration Assistant to transfer data, and handle special considerations like CI pipelines and forked repos. By cleaning up your environment, communicating with your team, and following best practices such as test runs and downtime planning, you can drastically reduce the risks of moving to the cloud. Your developers will appreciate a transition that feels orderly and well-managed, letting them continue coding with little interruption. A successful migration isn’t just about moving data it’s about setting your team up on a solid foundation in the cloud, with optimized workflows and confidence in the new system.