Migrate your repositories to GitHub: A step-by-step guide

There are many options if you want to switch GitHub products, such as from GitHub Enterprise Server to the Cloud or from other code hosting platforms, such as GitLab. When this happens, you’ll want to take your work with you, such as your code, your code history, or all your past conversations and collaborations.

GitHub offers a variety of tools to help you with these migrations that provide different levels of fidelity. We’ve compiled best practices and some examples so you can start your migrations as soon as possible.  

Migrating to GitHub: Best Practices

The first thing you should consider before starting the migration is to define what you want to migrate and when. Once you are clear on this, you need to determine where the data will be moved from. Depending on the size and complexity of your business, you may be using several different code hosting platforms.

And, of course, you need to be clear about which GitHub product you are migrating to – your migration destination.  

Building a basic inventory

Once clear on these two points, you need to specify what data you need to migrate.

Create a migration inventory with a list of all the repositories in your migration sources that you will migrate. This should collect data such as name, owner, URL, last updated timestamp, number of pull requests, and number of releases.

Whichever approach you choose for your inventory, note the process you followed or the commands you executed. Once you have the list of repositories, you can choose which one to migrate. This will also be the perfect opportunity to evaluate and remove the ones that are not needed, which will greatly simplify the migration.  

Measuring sizes

Once you have your basic migration inventory, gather information about the size of your repositories. Large repositories can make the migration take longer and limit the tools available to you.

If you use Git as your version control system, it’s not just the large files that matter but also the history of the repository. To continue, you’ll need to add the following data to the inventory for each repository: the largest file size (blob) and the total size of all files (blobs).

If, on the other hand, you use a different version control system or the files are not tracked by one, you should first move the repositories to Git. Then, use git-sizer to get this data.  

Deciding on the type of migration

When deciding which type of migration to choose, you should consider the needs of your business and the tools available. In fact, you can choose different strategies depending on the type of repository.

The three approaches to do so are: 

1. Source snapshot: the current state of the code is migrated without any revision history. This is possible for all sources and targets, even if the code is not yet tracked in a version control system.
2. Source and history: the current state of the code and its history are migrated. This is only possible if the changes are tracked in Git or in a version control system that can be converted to Git before migration.
3. Source, history, and metadata: the current code, its revision history, and collaboration history (issues, pull requests and configurations) are migrated. Requires specialized tools that are not available for all migration paths.  

Designing the structure of the organization

Each repository belongs to an organization, which is a shared account where companies and open-source projects can collaborate on several projects at once.

This is why it is so important to define the most effective structure for each organization and repository after migration. This design can maximize collaboration and minimize administrative burden or create silos and unnecessary overhead.

GitHub recommends minimizing the number of organizations and structuring it according to one of five archetypes. 

Perform a test

Before proceeding with planning, it is beneficial to perform a test migration that includes all your repositories.

This test will allow you to verify that the chosen tools work for you, that they meet your requirements, you will better understand which data is migrated and which is not, as well as the time it will take to migrate.  

Pre- and post-step planning

There will be some data or settings that you will need to do manually. The steps necessary to do this will depend on each specific circumstance, but the most important prerequisites are: 

• Inform your users about the timing of the migration.
• Set up user accounts for the team.
• Send instructions to update local repositories pointing to the new system. 

Post-migration steps must also be taken into account: 

• Inform users that the migration has been completed.
• Link the activity to the users at their origin-destination.
• Dismantle the migration origin.  

Continuous Integration (CI) and Continuous Delivery (CD) migration

If you’re already moving between GitHub products, you’ll be using GitHub Actions for CI/CD, and there’s not much to do about it, as the workflow files in your repositories will be migrated automatically.

If, on the other hand, you are not using GitHub Actions, the situation is more complicated. You will need to verify that your CI/CD provider is compatible with GitHub and connect it to your new organization and repositories.

However, if you want to switch to GitHub Actions, it is not recommended to do so at the same time as migrating your repositories. It’s better to wait until you’re done and migrate the CI/CD as a separate step.  

Equipment management and permissions

If you migrate collaboration history or metadata, you will need to link users’ activity to their new identities at the migration destination. The attribution process is what will allow you to do this.

You can then create your teams and add team members before migrating your repositories. You can manage them through your identity provider (IdP), linking your teams to IdP groups.  

GitHub Migration Partner

When it comes to migration, you can opt for a self-service migration, where you plan and execute your own migration without any professional support from GitHub. However, the best option is to rely on a professional in the field where you can benefit from the knowledge and experience of an expert.

If you need a specialized partner and you don’t know who to choose, here are several reasons to choose Plain Concepts: 

• We are the first partner in Spain accredited by GitHub.
• We have been working for more than 17 years in the Agile culture, a benchmark in the DevOps community.
• We have a team of more than 350 senior engineers specializing in app innovation and DevOps.
• AMMP accredited.
• DevSecOps with MVPs.  

You will gain numerous benefits, such as the key points of migrations and pitfalls to avoid, your staff training for the upcoming migrations, documentation of the migration process, and, finally, the migrated repositories.

If you want to start your migration now, don’t wait any longer to contact us, and our team of experts will be happy to help you get started.