Export and import projects and repositories

Administer Bitbucket Data Center and Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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:

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

GitGit repositories on file system(tick)(tick)
Pull requestsPull request metadata(tick)(tick)

PR user info(tick)(tick)

PR comments(tick)(tick)

PR attachments(tick)(tick)

PR File comments(tick)(tick)
Project SettingsDescription(tick)(tick)

Project permissions (user access)(tick)(tick)

Project permissions (group access)(tick)(tick)

Project permissions (public)(tick)(tick)

Project permissions (default permission)(tick)(tick)
Repository SettingsDefault branch(tick)(tick)

Forks(tick)(tick)

Transcode diffs(tick)(tick)

LFS enabled(tick)(tick)

Repo permissions (user access)(tick)(tick)

Repo permissions (group access)(tick)(tick)

Repo permissions (public access)(tick)(tick)

Git hooks on disk(tick)(tick)
Data/settings not migrated

Here's the list of items that are not migrated:

  • Git LFS
  • Access keys
  • HTTP access tokens
  • Webhooks
  • Default reviewers
  • Default tasks
  • Merge strategies
  • Merge checks
  • Hooks
  • Branching model
  • Branch permissions
  • Commit comments
  • Commit file comments
  • Tasks
  • Likes/reactions
  • Linked Jira issues
  • Build status
  • Watchers
Last modified on Mar 24, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.