Migrate a Bitbucket Cloud workspace to another workspace
Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.
Summary
This KB provides a step-by-step guide on migrating from one Bitbucket Cloud workspace to another.
You can use if you want to migrate to a Bitbucket workspace with unified user management.
Environment
Only applicable to migrate one Bitbucket cloud workspace to another Bitbucket cloud workspace.
For migration from Bitbucket Server or Data Center to Bitbucket Cloud, please use the Bitbucket Cloud Migration Assistant.
Solution
The steps in this guide are manual. If you prefer an automated way, you can use this script. Please keep in mind the following:
This script will only work if your current workspace has user management in Bitbucket's website and the new workspace you will migrate to has user management in Atlassian Administration. By default, any workspace you create now has user management in Atlassian Administration, but you need to double-check if your current workspace has user management in Bitbucket.
This script is considered a third-party tool and it is NOT supported by Atlassian.
You will still need to check the Post-migration cleanup section of this guide for any settings not migrated with this script.
Before starting, please communicate the migration plan with your team to ensure proper planning and execution.
Here is a step-by-step guide to help you migrate from one Bitbucket Cloud workspace to another:
Create a new workspace
Please keep in mind that the new workspace you create will have a different ID from the existing one, so the URL of the repositories will change once you transfer the repos. If you want to keep the same ID in the new workspace, you will first need to change the ID of the existing workspace to a different one, in order to free up the ID. You need to have administrator access to the old / existing workspace to change its ID. Afterwards:
Create a new Bitbucket workspace by following our guide: How to create a Bitbucket workspace
Recreate projects in the new workspace
If you want to keep the old workspace's project structure in the new workspace, you will need to create the projects in the new workspace.
Check what projects the old workspace has in https://bitbucket.org/workspace-id/workspace/projects/ (replace workspace-id in the URL with the ID of the old workspace).
Create the projects in the new workspace.
Transfer the repositories
You need to have admin access to the repositories of the old workspace in order to perform these steps. If you don't, please ask an admin to perform these steps.
If you use Bitbucket Pipelines and Deployment variables on certain repositories, please keep in mind that Deployment variables are not transferred at the moment. Make a note of the Deployment variables used in a repo and their value, so you can recreate them after the repo transfer.
For each repository in the old workspace:
Open the repository on Bitbucket's website.
Select Repository settings from the left sidebar.
Select Repository details from the new left sidebar.
On the new page, select Manage repository from the top right corner of the screen.
Select Transfer repository.
In the dialog that appears, enter the Workspace ID of the new workspace you created in Step 1.
Select Transfer.
If you have a large number of repos, you can use this script to automate this step. Please keep in mind that this script is a third-party tool and it is NOT supported by Atlassian.
Repeat these steps for all repositories you wish to migrate. Bitbucket will send an email to the new owner or workspace administrators containing the transfer request with a link to the page that allows the user to accept or reject the transfer.
Accept the repositories transfer
If you receive a transfer request, accept it by doing the following:
Open the transfer request email.
Select the link View transfer request in the email to open the Transfer repository ownership screen. If you're not logged in to Bitbucket, you'll have to log in first.
You can see the current workspace where this repo belongs and the new one where it will be transferred. Right below that, you will need to select the project in the new workspace where you want this repo to belong post transfer.
Select Accept.
Once you accept the request, the repository will appear in the repository list of the new workspace. Bitbucket updates all URLs on the server and the repository is accessible from its new location.
Post-migration cleanup
You will need to configure user groups and invite users in the new workspace. Any new Bitbucket workspace you create has user management in
Atlassian Administration. Default groups are created for your Bitbucket workspace in Atlassian Administration, but you can also create new groups. Please see the documentation on how to see the default groups, create new ones and on how to invite users.
The user groups you create will need to be given access to the repositories in the new workspace. By default, only the administrators group is added to the Bitbucket projects and repositories. You can grant access to additional groups on Bitbucket's website, either on the project level (from Project settings > Project permissions) or on the repository level (from Repository settings > Repository permissions).
If you use Bitbucket Pipelines with Deployment variables in certain repos, recreate the Deployment variables in the transferred repos as per the notes you kept in Step 3.
If the Projects of the old workspace had specific settings (Access keys, Branch restrictions, Branching model, Merge strategies, Default reviewers) that you want to keep in the new workspace, you will need to configure the same settings in the projects of the new workspace (from Project settings).
You will need to configure Workspace settings in the new workspace. Example of such settings are workspace privacy, forking settings, access controls, workspace SSH keys, runners, workspace variables. If you are a workspace admin, open the workspace on Bitbucket's website, select the cog icon (top right corner of the screen) > select Workspace settings. You can then navigate to the different settings from the left sidebar.
If your new workspace now has a different ID than the old one (see Step 1), the URLs of the repos will be different. Users working on the workspace's repos will need to update their local repositories' URL to the new URL.
Was this helpful?