About migrations from Bitbucket Server to GitHub Enterprise Cloud

Learn which data GitHub Enterprise Importer can migrate.

In this article

About migrations from Bitbucket Server

You can use GitHub Enterprise Importer to migrate repositories from Bitbucket Server to GitHub Enterprise Cloud (GitHub.com or GHE.com). Migrations from Bitbucket Server are only supported for Bitbucket Server or Bitbucket Data Center version 5.14+ or higher.

Data that is migrated

We currently only support migrating the following repository data from Bitbucket Server to GitHub Enterprise Cloud.

  • Git source (including commit history)

  • Pull requests (including comments, pull request reviews, pull request review comments at the file and line level, required reviewers, and attachments)

    Note

    Users may receive a 500 error when attempting to view a pull request, if the pull request was merged and the head branch deleted on Bitbucket Server prior to migration. Bitbucket Server removes specific Git references to objects for such pull requests, and consequently those Git objects associated with the pull request are unable to be migrated.

Data that is not migrated

Currently, the following data is not migrated.

  • Personal repositories owned by users
  • Branch permissions
  • Commit comments
  • Repository settings
  • CI pipelines

Limitations on migrated data

There are limits to what GitHub Enterprise Importer can migrate. Some are due to limitations of GitHub, while others are limitations of GitHub Enterprise Importer itself.

Limitations of GitHub

  • 2 GB size limit for a single Git commit: No single commit in your Git repository can be larger than 2 GB. If any of your commits are larger than 2 GB, you will need to split the commit into smaller commits that are each 2 GB or smaller.
  • 255 byte limit for Git references: No single Git reference, commonly known as a "ref", can have a name larger than 255 bytes. Usually, this means that your references cannot be more than 255 characters long, but any non-ASCII characters, such as emojis, may consume more than one byte. If any of your Git references are too large, we'll return a clear error message.
  • 100 MB file size limit: No single file in your Git repository can be larger than 100 MB. Consider using Git LFS for storing large files. For more information, see "Managing large files."

Limitations of GitHub Enterprise Importer

  • 10 GB size limit for a Git repository: This limit only applies to the source code. To check if the repository archive is over the limit, use the git-sizer tool and review the total blob size in the output. The git-sizer tool also helps to identify potential issues related to large files, blob size, commit size, and tree counts that could impact migrations.
  • 10 GB limit for metadata: The Importer cannot migrate repositories with more than 10 GB of metadata. Metadata includes issues, pull requests, releases, and attachments. In most cases, large metadata is caused by binary assets attached to releases. You can exclude releases from the migration with the migrate-repo command's --skip-releases flag, and then move your releases manually after the migration.
  • Git LFS objects not migrated: The Importer can migrate repositories that use Git LFS, but the LFS objects themselves will not be migrated. They can be pushed to your migration destination as a follow-up task after the migration is complete. For more information, see "Duplicating a repository."
  • Follow-up tasks required: When migrating between GitHub products, certain settings are not migrated and must be reconfigured in the new repository. For a list of follow-up tasks you'll need to complete after each migration, see "Overview of a migration between GitHub products."
  • Delayed code search functionality: Re-indexing the search index can take a few hours after a repository is migrated, and code searches may return unexpected results until re-indexing is complete.
  • Rulesets configured for your organization can cause migrations to fail: For example, if you configured a rule that requires email addresses for commit authors to end with @monalisa.cat, and the repository you're migrating contains commits that don't comply with this rule, your migration will fail. For more information about rulesets, see "About rulesets."
  • Mannequin content might not be searchable: Mannequins are placeholder users to which imported content (such as issues, pull requests, comments, etc.) is associated. When you search for content associated with a mannequin, such as assigned issues, the issues may not be found. Once a mannequin is reclaimed, the content should be found via the new owner. For more information, see "Reclaiming mannequins for GitHub Enterprise Importer."

Getting started

Before you migrate from Bitbucket Server, you should plan out how you will run your migration. Before migrating any data, you will need to choose someone to run the migration. You must grant that person the necessary access for both the source and the destination of the migration. We also recommend you run a trial migration first.

For an overview of the migration process from beginning to end, see Overview of a migration from Bitbucket Server to GitHub Enterprise Cloud.