How to Migrate From Bitbucket to GitHub

GitHub is focused on public code and Bitbucket is meant for private code. That’s the most basic difference between the two code repositories. Also, being an open-source community, GitHub has a massive user base mostly comprising individual developers while Bitbucket has more enterprise and business users.

While both are excellent platforms, many developers are increasingly migrating their repositories from Bitbucket to GitHub.

Why? There can be all kinds of subjective and objective reasons for migrating to GitHub, but mostly it all boils down to price and license limitations. The number of available private or public repositories is important and migration to another platform may be more profitable. The fact that more and more tools are offering better out-of-the-box integration with GitHub is another factor.

If you also plan on joining the bandwagon, you need to know the right steps. Below is a step-by-step breakdown of how to migrate from Bitbucket to GitHub.

First Things First, What are GitHub and Bitbucket?

GitHub hosts projects that use the Git version control system (VCS). It isn’t compatible with any other projects, but as Git is the most commonly used VCS by a considerably large margin, GitHub is the largest code host among all platforms.

Here’s a list of a few notable GitHub features:

• Branch comparison views
• Offers milestones and labels within projects
• Includes an integrated issue tracker within projects
• Native apps for Windows, Mac, and Android devices
• Has a unique GitHub Pages feature that is useful for publishing and hosting within the platform
• Offers API integration for easy integration with third-party tools and a large number of other platforms and tools like Asana, Travis, and Windows Azure
• Excellent wiki support that lets you document and share projects with team members and centers, facilitating fast and easy collaboration

Bitbucket is another immensely popular code repository that supports Git. It’s a centralized place that lets you manage Git repositories and collaborate on your source code. While this article is about migrating from Bitbucket to GitHub, many users have also migrated over to Bitbucket from GitHub following Microsoft’s recent acquisition of the platform.

Here’s a list of a few notable Bitbucket features:

• Access control to limit unauthorized access to source code
• Pull requests with in-line commenting for easy collaboration when reviewing code
• Workflow control to enforce a team or project workflow
• Full Rest API to build features customized to your project workflow
• Easy integration with tools like Jenkins, Jira, Bamboo, Crucible, HipChat
• Built-in continuous delivery, along with issue tracking and wikis
• Offers Git Large File Storage (LFS) support for shorter clone and fetch times for users working with large files

3 Easy Steps to Migrate from Bitbucket to GitHub

Now that you have an idea of what to expect from each platform, let’s look at the steps to migrate from Bitbucket to GitHub.

1. Create a Blank GitHub Repository

The first step is to create a new private repository on GitHub.com. 

Note you need to keep this repository empty, which means not checking the Initialize this repository with a README option when creating it. Your repository should be blank on GitHub without README.md.

2. Move Existing Bitbucket Repository Content

The next step involves filling the GitHub repository with all the code and content from Bitbucket.

First, check your existing repository from Bitbucket. Use the following code to do this:

$ git clone https://USER@bitbucket.org/USER/PROJECT.git

Next, you need to add the new GitHub repository of the repository’s upstream remote checked from Bitbucket. Use the following code to move the existing content to GitHub:

$ cd PROJECT

$ git remote add upstream https://github.com:USER/PROJECT.git

Finally, you’ll have to push all branches and tags to the GitHub repository. Here’s the code for this:

$ git push upstream master

$ git push –tags upstream

3. Clean Up The Old Repository

Having two repositories for the same project can be confusing for the developers—and sometimes, even you. Keeping this in mind, we recommend deleting the Bitbucket repository.

Here’s how to go about this:

1. Ensure your new GitHub repository has all the code and content from your Bitbucket repository.
2. Open the web interface of your old Bitbucket repository.
3. In the menu, select Setting followed by Delete repository.
4. After moving the code and content, you also need to add the URL of your new GitHub repository as a redirect URL to ensure users visit the right page. Add the URL of your new GitHub repository as a redirect URL. Here’s the code to do this:

$ git remote set-url origin git@github.com:devops-school-com/ds-test.git

While you’re at it, you should also clone all branches and tags to the GitHub repository. In this case, we recommend using the –mirror parameter:

$ git push –mirror

Common Problems When Migrating from Bitbucket to GitHub

In this section, we’ll briefly discuss the common issues developers face when migrating from Bitbucket to GitHub. 

Let’s take a look.

Problem 1: Increasing Complexity Because of a Large Number of Repositories

Developers make the common mistake of assuming that migrating their codebase to a completely different platform is a straightforward process. As a result, they don’t consider the number of repositories they need to migrate and, therefore, don’t change the actions that end up increasing the complexity of the project.

It’s important to analyze the number of repositories you want to migrate, and then design a plan of action to ensure the migration process is seamless and smooth. For instance, you can consider creating a Jenkins pipeline to sync a large number of repositories to eliminate unnecessary complications. 

You can also use specialized tools to generate your repositories with the proper user access, data, and branch restrictions. You may also need to use other processes to create the repositories and migrate the metadata

Your migration plan should also be influenced by the dependencies between repositories. Set the order in which the repositories will be migrated to avoid pain points down the line.

Problem 2: Forgetting About the Snippets

If you have snippets, you’ll need a separate pipeline to sync them because snippets don’t exist in the same way in GitHub as they do in Bitbucket. 

As such, you have to clone them and create a temporal project to include all of them. This will automatically lead to a project called “snippets“ in GitHub that will contain a folder with the data for each snippet.

It’s also important to note that managing huge files is different in repositories for each tool. In Bitbucket, you don’t have per-file limits, which is existent in GitHub. In fact, the latter has hard restrictions relating to files with more than 100 MB. In these cases, we recommend using a Git LFS tool and managing your files with it.

Problem 3: Having a Team That’s Unfamiliar With GitHub

One of the main reasons why developer teams face problems when migrating from Bitbucket to GitHub is because the members are unfamiliar with the former platform. Due to this, they cannot hit the ground running and identify potential issues, which often leads to errors and complications.

While you don’t need a full-fledged team of GitHub experts if you aren’t a large enterprise, it’s still recommended to have some level of familiarity to prevent issues during the migration process and avoid rollback.

As your team starts to work with GitHub, provide them with all the resources they need to prepare and adapt the previous processes to synchronize GitHub with Bitbucket. Be sure to plan carefully and outline all the steps to avoid any major issues.

Additional Nira Posts to Check Out

If you want to learn more about GitHub and Bitbucket, here are a few articles to help you familiarize yourself with the nitty-gritty of each platform.

• Bitbucket vs. GitHub — Weigh the pros and cons of both code repositories to find out the best option for your organization.
• How to Use GitHub and How to Use Bitbucket — Use our step-by-step tutorials to know the right way to use GitHub and Bitbucket, as well as find out the solutions to eliminate common problems while you work on each platform.
• The Ultimate Manual to Bitbucket Cloud — Bitbucket offers a special cloud service that lets you host, set up, secure, and maintain your software in the cloud. This also means you don’t have to worry about maintaining your physical repository hardware. 
• How to Migrate from GitLab to GitHub — Do you want to also learn how to migrate from GitLab to GitHub? Don’t worry; we’ve got you. Learn three different ways to migrate seamlessly and with no complications.