Planning your migration to GitHub - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Planning your migration to GitHub Plan and execute a successful migration to GitHub or between GitHub products. In this article About migrations If you're moving between GitHub products, such as from GitHub Enterprise Server to GitHub Enterprise Cloud, or from another code hosting platform, such as Bitbucket Server or GitLab, to GitHub, you'll want to bring your work with you: your code, the code's history, and all of your past conversations and collaboration.
This guide will help you through planning and executing a successful migration. You’ll learn how to prepare for a migration, the tools that are available to move your data, and how to make your move a success. Migration terminology Before using this guide to plan your migration, learn these important terms. Term Definition Code hosting platform The online tool that you use to host your source code repositories and to collaborate, such as GitHub Enterprise Cloud, GitHub Enterprise Server, Bitbucket Server, and GitLab.com.
Version control system (VCS) The tool that you use to track and manage changes to your source code on the machine where you’re making those changes. For example, if you’re using GitHub or GitLab as your code hosting platform, you’re using the Git version control system. If you’re using Azure DevOps as your code hosting platform, you could be using either Git or Team Foundation Version Control (TFVC) as the underlying version control system.
It's also possible that you aren’t using a VCS at all. Migration origin The place you’re migrating from. Usually, this will be a code hosting platform, but it might be your own machine or a shared network drive. Migration destination The GitHub product that you’re moving to. Migration path The combination of your migration origin and migration destination, such as “Bitbucket Server to GitHub Enterprise Cloud.” For certain migration paths, GitHub offers specialist tools, such as GitHub Enterprise Importer, to help you migrate.
Defining your migration scope Before you can plan your migration, you need to understand what you want to migrate, and when. Defining your origin and destination First, determine where you need to move data from. This is usually, but not always, a code hosting platform. Your code hosting platform might be a GitHub product, such as GitHub.com or GitHub Enterprise Server, or it might be another code hosting platform, such as Bitbucket Server, GitLab, or Azure DevOps.
Depending on the size and complexity of your business, you might be using multiple different code hosting platforms. If you’re not using a code hosting platform at all, you might be storing your code on a shared network drive, for example. Wherever your code lives, that's your "migration origin." You’ll also need to know which GitHub product you’re migrating to, or your "migration destination." This could be GitHub.com, GHE.com, or GitHub Enterprise Server.
Building a basic inventory of the repositories you want to migrate After you've identified your migration origin and destination, establish what data you need to migrate. You should build a migration inventory with a list of all of the repositories in your migration origin(s) that you need to migrate. We recommend using a spreadsheet. As a starting point, you should record the following data for each repository: Name Owner: in GitHub, this would be an organization, but in other tools, there might be a different kind of owner URL Last updated timestamp Number of pull requests (or equivalent in your migration origin) Number of issues (or equivalent in your migration origin) If you’re migrating from GitHub Enterprise Cloud or GitHub Enterprise Server, you can obtain this data with the gh-repo-stats extension for the GitHub CLI.
With just a few commands, gh-repo-stats will connect with your migration origin's API and create a CSV with all of the recommended fields. For more information, see the mona-actions/gh-repo-stats repository. Note gh-repo-stats is a third-party open-source tool which is not supported by GitHub Support. If you need help with this tool, open an issue in its repository. If you’re migrating from Azure DevOps, we recommend the inventory-report command in the ADO2GH extension of the GitHub CLI.
The inventory-report command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. For more information about how to install the ADO2GH extension of the GitHub CLI, see Migrate your repositories from Azure DevOps to GitHub . If you’re migrating from Bitbucket Server or Bitbucket Data Center, we recommend the inventory-report command in the BBS2GH extension of the GitHub CLI.
The inventory-report command will use your Bitbucket instance's API to build a simple CSV. For more information about how to install the BBS2GH extension of the GitHub CLI, see Migrating repositories from Bitbucket Server to GitHub Enterprise Cloud . Depending on your migration path, there are various tools you can use to collect this data: If your source is another GitHub product, the third-party gh-repo-stats extension for the GitHub CLI.
If your source is Azure DevOps, GitLab, or Bitbucket, the inventory-report command for GitHub Enterprise Importer. For other migration origins, you could build the spreadsheet using the origin’s reporting tools or API, or you could create the inventory manually. You will find detailed information on using these tools in our documentation for the specific migration path. Whatever approach you choose for your migration inventory, make a note of the process you followed or commands you ran.
It’s very likely that you’ll want to re-run your inventory as you continue to plan your migration. After you have a list of all of your repositories, you can decide which ones you want to migrate. One option is to migrate absolutely everything. However, a migration is a great opportunity to evaluate your repositories and remove any that are no longer needed. We find that many business have hundreds or even thousands of unused and unneeded repositories, and archiving them can make your migration much simpler.
Measuring the sizes of your repositories After you’ve completed your basic migration inventory, collect information about the size of your repositories. If your repositories are large or contain individual files over 100MB, this can make your migration longer and riskier and limit the migration tools that are available to you. If you’re using Git as your version control system, it's not only large files currently in the repository that matter; large files in your repository's history matter too.
For example, if you had a file larger than 100MB in your repository in the past, then that file will still be present in your Git history, unless you’ve rewritten the history to remove all traces of the file. For more information about rewriting history, see About large files on GitHub . If you used gh-repo-stats to build your inventory, you’ll already have some basic information on how big your repositories are. To build a complete migration inventory, you'll need to obtain finer details about the data inside your repositories.
Next, follow the instructions below to add the following data to your migration inventory for each repository: The size of the largest file (also known as a “blob”) The total size of all files (“blobs”) If you’re using a version control system other than Git, or your files aren’t tracked with a version control system at all, first move the repositories to Git. For more information, see Adding locally hosted code to GitHub .
Then, use the open-source tool, git-sizer , to get this data for your repository. Prerequisites Install git-sizer . For more information, see the github/git-sizer repository. To verify that git-sizer is installed, run git-sizer –version . If you see output like git-sizer release 1.5.0 , install
The rest of this page is on the live site.