Export and import projects and repositories
Data Center Migration is a tool for admins that can be used to:
- consolidate multiple Bitbucket instances
- move from a Bitbucket Server to a Bitbucket Data Center instance
- selectively export/import projects and repositories from one Bitbucket Data Center instance to another
Git data can be imported or exported into Bitbucket Data Center from another Bitbucket Server or Data Center deployment, along with pull requests, comments and attachment history.
This feature is only available to customers with a Bitbucket Data Center instance.
Before starting a migration, review the below information carefully. There is also information around troubleshooting, canceling and cleanup, and error and warning messages.
Before you start
This is a high-level description of considerations and tasks to review and complete before performing a migration. Read through the following sections carefully before starting a migration.
User Interface
There's no graphical user interface in the initial (Bitbucket Server 5.14) release of this feature. Instead, REST calls can be made to control the migration process.
To perform the migration you will need to either:
- use your favorite tool to make REST calls, or
- refer to the provided sample cURL commands for import and sample cURL commands for export.
If you plan to use cURL commands, we recommended you setup a .netrc file (sample commands use the -n flag) and install jq on your machine.
Using the preview REST endpoint
You can use the preview function to review the scope of the export, prior to a migration.
The preview takes into account fork hierarchies, which are always migrated fully.
Disk space requirements
Always make sure you have enough disk space for the files you're migrating. The space required on disk during export is roughly the size of the Git data and attachments being exported.
Additional space is required for ElasticSearch, and for your database server.
If you are unsure what space you have available, the following knowledge base article tells you how to identify a repository ID in Bitbucket, which you can then use to check the available disk space.
Issues with project name conflicts
Before migration, check the names of projects on both the source and destination instances. If a project name is in use on the destination instance, the project being imported will be renamed.
To avoid this either:
- check all project names and rename before migration, or
- after the migration, review the warnings on the import job, and rename projects manually.
The same logic applies to repository names in personal projects.
Time needed for export
There is no real way to predict the time required for the export, it is impacted by your data set, individual load, and traffic.
Some tests have shown that an export of 200GB can take anywhere between 2 - 4 hours, but this can be higher.
Time needed for import
There is no real way to predict the time required for import, it is impacted by the size of the export archive being imported, the number of pull requests, and the number of repositories.
An import will take longer than an export (roughly four times as long). This is because indexing and validation (performed during import) doesn't occur during export, and remains dependent on your data set, individual load, and traffic.
User and license management recommendations
Non-active users are added to a generated list of "deleted users" on export, and do not take up licenses on migration.
We strongly recommend that both the source and destination instances are connected to the same user directory prior to migration.
Even though users will not be migrated, their permissions on projects and repositories will, and permissions are matched by username. If users are missing on the destination instance, permissions might not be migrated and a warning will be logged.
If user directories are different on both instances, it is possible that users with the same username exist on the destination instance, but are actually different users in the source instance. This would result in incorrect permissions being granted to those users on import.
Third party plugins
It's important to know that third party plugins will not be migrated, neither will their data.
Plugins can implement their own migrations using this API.
Pull request comments
If a pull request comment references an attachment that was uploaded to a different repository, there is a possibility that the attachment will not be successfully imported.
E.g if a user has uploaded an attachment to a comment on a pull request in one repository, then copies and pastes the link into a different comment on a pull request, in another repository.
This will not impact the import of the rest of the comment, only the attachment.
For more information see the troubleshooting, canceling and cleanup page.
Entities included in migration
The below table lists the entities that will be imported and exported during migration.
- Data/settings not included in the below table are not migrated (for example, repository hooks, Git LFS)
- Git LFS objects migration needs to be run separately. You can use this Git LFS migration process to export these objects (LFS objects on file system).
Category | Item | Import | Export |
|---|---|---|---|
| Git | Git repositories on file system |  | |
| Pull requests | Pull request metadata | | |
| PR user info | | | |
| PR comments | | | |
| PR attachments | | | |
| PR File comments | | | |
| Project Settings | Description | | |
| Project permissions (user access) | | | |
| Project permissions (group access) | | | |
| Project permissions (public) | | | |
| Project permissions (default permission) | | | |
| Repository Settings | Default branch | | |
| Forks | | | |
| Transcode diffs | | | |
| LFS enabled | | | |
| Repo permissions (user access) | | | |
| Repo permissions (group access) | | | |
| Repo permissions (public access) | | | |
| Git hooks on disk | | |