How to Migrate from GitHub Enterprise Server to Enterprise Cloud
Moving from GitHub Enterprise Server to Enterprise Cloud can feel like an overwhelming task. This step-by-step guide will teach you how to do it and how to overcome the most common challenges.
Continue below to learn more about migration from Enterprise Server to Enterprise Cloud on GitHub.
Step #1: Set Up Your Enterprise Cloud Account
Even if you’re a current GitHub Enterprise Server user, you’ll still need to set up an Enterprise Cloud account before you can proceed.
Enterprise Cloud accounts let you manage policies and billing for multiple organizations from a centralized dashboard. In this scenario, one of the organizations can ultimately be your existing Enterprise Server account. However, the data sharing won’t be as simple as sharing between two Enterprise Cloud organizations.
Depending on how you’re currently using GitHub, you’ll have two options to consider when setting up your cloud account.
- Create a new organization from scratch
- Upgrade your GitHub subscription
The first is for new GitHub Cloud users, and the latter is for existing accounts.
Once the account has been created, you can add members and organization permissions, set up user roles, create teams, manage team settings, grant access to repositories, apps, project boards, and more. It’s important to get this stuff out of the way early so you’re not scrambling to revoke access from certain users after the migration.
Step #2: Configure Backups on Your Enterprise Server
Before you start the export or migration, you need to set up a disaster recovery plan. For those of you who don’t already have a server backup, now is the time to do so.
The easiest way to do this is through GitHub Enterprise Server Backup Utilities. This method requires a Linux or Unix system host that’s separate from your Enterprise Server.
GitHub also recommends putting your backup somewhere that’s geographically distant from your existing server location. This ensures that the backups will be recoverable if there’s a local disaster or network outage near your primary server.
The physical storage requirements of your backup will ultimately vary based on the disk usage of your Git repos and expected growth. But generally, GitHub recommends using two vCPUs, two GB of memory, and five times the storage of your primary instance.
Next, you can schedule regular backups using a cron(8) command or another scheduling service. GitHub recommends starting with hourly backup schedules to ensure the worst-case scenario for primary data loss is limited to just one hour of work.
Once all of your data has been backed up, you can proceed with the next migration steps.
Step #3: Export Your Enterprise Server Repositories
To export your enterprise service instances, you must verify your administrative privileges on the Enterprise Server source. Using SSH into the instance is the simplest approach here.
Next, generate an access token using the repo and admin:org scopes from the Enterprise Server source instance.
You can manually make a list of the repos you’re planning to export as a way to minimize downtime during this step. Then you can add multiple repos at once to a single export simultaneously with a text file that has the URL of each repository on separate lines.
Follow the migration prompts on the screen for the authorized user, personal access token, and other commands. Once all of the repositories have been exported, you’ll need to close the connection to the server instance.
Then just copy the migration archive to your machine using the SCP command.
Step #4: Create a New Repository Enterprise Cloud
Now you need to get organized back in your Enterprise Cloud account. Create a new repository, and give it the same name as the repository you’re going to migrate.
GitHub will give you the SSH address of your new repository for adding it remotely. You can follow the quick setup option here.
Then just copy the URL, and add it to the terminal where the local repository will get pushed.
Now you can push the new repository as a remote repository using the cloned export from your Enterprise Server. Use new-origin and –all flag commands to ensure that all your branches get transferred.
If you refresh your GitHub Enterprise Cloud account, you should see the new repo and all of its branches updated. Then just make sure you inform your team of these changes, so everyone updates their origin remotes accordingly.
Step #5: Migrate Your Data
The previous step moves your repositories but doesn’t move the rest of your GitHub data. You still need to transfer your projects, pull requests, issues, comments, repository metadata, and everything else.
This data is not stored in Git. You must use the GitHub API to migrate the rest of your data to your new repositories.
Migrating the rest of your data is a bit time-consuming, as you can’t do it all at once. That’s because there’s no simple way to consolidate everything into a single migration or bulk migration.
Download the data from your Enterprise Server repository. You can start with issues, projects, or whatever you decide—the order doesn’t matter.
To download the data files, you’ll need your username and personal access token for both the Enterprise Server and Enterprise Cloud accounts.
Once the file has been produced, you can move it to Enterprise Cloud using GitHub’s API. For example, a file like issues.json will contain all the issues for one particular repository.
Continue repeating this process of downloading the Enterprise Server data and uploading it to the Enterprise Cloud with the API for each dataset you want to migrate.
Common Problems When Migrating from GitHub Enterprise Server to Enterprise Cloud
GitHub Enterprise Server is an on-premises git repository hosting solution. This gives larger organizations more control over and security options over their code and repositories. Enterprise Server gives you the option to set access limits on private networks, impose access control rules, and use SSO with SAML organization-wide.
GitHub Enterprise Cloud provides enterprise-grade features, security restrictions based on the user’s network, SAML sign-on, and a 99.95% uptime SLA. Arguably the greatest benefit of Enterprise Cloud is the fact that you won’t have to maintain the infrastructure on your own like you would with an Enterprise Server.
Even for tech-savvy users, moving from GitHub Enterprise Server to Enterprise cloud can pose some challenges.
This type of migration isn’t quite as common as moving from GitHub Team to Enterprise Cloud, which is much more straightforward. Even migrating data from another source to either Enterprise plan is more common than a move from Enterprise Server to Enterprise Cloud.
Below we’ll talk about the most common stumbling blocks associated with this initiative and how you can overcome them.
Problem #1: Lack of Official GitHub Documentation
GitHub is the most popular version control software and code repository on the planet. There are tons of great resources in GitHub Docs across every category and question imaginable.
There are some basic articles about getting started, billing, and administrative resources, as well as some technical documentation related to pull requests, repositories, CodeQL, and more.
When you have a question related to GitHub, navigating to Docs for an answer is usually your best bet. If you can’t find an answer here, you can always ask the GitHub community for help, and someone in the network of 73+ million developers will likely have an answer.
With that said, there’s no official GitHub documentation for migrating from Enterprise Server to Enterprise Cloud. This is pretty surprising, considering the depth of the existing resources.
There are some articles that are semi-related to the topic, like:
- Migration for an Enterprise
- Export from your Enterprise
- Export data from GitHub.com
- Prepare to migrate your data
- Import to your enterprise
- Import from another CVS
But none of these actually explain the process or steps for going from Enterprise Server to Enterprise cloud. There’s actually more documentation related to migrations from a third-party version control system than information for this particular use case.
If you browse the web, you’ll find only a handful of tutorials from other sites explaining how to accomplish this process. Most of the solutions are fairly complex.
The lack of official documentation from GitHub about this type of migration says it all—there’s no simple way to migrate from GitHub Enterprise Server to Enterprise Cloud, and it’s not a common question.
That shouldn’t discourage you from going through this process. But you should still be aware that you won’t be able to follow any official tutorials from GitHub.
Problem #2: Lack of Community Support
Similar to the lack of documentation provided by GitHub, the resources from the GitHub community are thin as well. This is pretty surprising, considering that the GitHub community usually thrives when it comes to troubleshooting these types of questions.
But it just goes to show that the request to go from Enterprise Server to Enterprise Cloud is both rare and challenging.
With that said, you can reach out to GitHub directly for assistance. All Enterprise plans come with standard support. But if you really want next-level service, it’s probably worth the investment to upgrade your plan to Premium Support.
Premium Support plans offer 24/7 service, upgraded from the 24/5 service offered with standard Enterprise support. The initial response of an urgent request is handled within 30 minutes, as opposed to eight hours for standard support.
In addition to web support, Premium plans offer phone support and screen sharing as well, which can be really useful to take advantage of when you’re going through this type of migration.
GitHub also offers a customer reliability engineer to customers on Premium Plus Support plans.
Even though GitHub doesn’t have official tutorials and documentation for your migration, it would be surprising if the Premium Support team left you in the dark if you reached out for assistance.
At a minimum, they can be there to help you troubleshoot different barriers you may encounter throughout your migration. You’ll know that someone will be there to help within 30 minutes, any hour of the day, any day of the week, as opposed to a response within eight hours, five days per week.
Problem #3: Sharing Public Repositories from Enterprise Server
There seems to be a common and logical thought when brainstorming workarounds for this migration. GitHub has an importer tool and API endpoint importer to simplify cloud migrations.
Both of these tools make it possible for you to enter the URL of a repository and validate the user credentials to import repositories from one source to the GitHub Cloud.
But there’s actually a significant issue with this logic. GitHub Enterprise Servers are designed to be private. They aren’t built to publicly share repositories.
Since most GitHub Enterprise Servers are deployed on private networks, this can be challenging. Even if the on-premises Enterprise Server is not installed on a private network, you must keep them on private mode to enable them.
In short, the straightforward method of using the GitHub importer tool or API endpoint importer solution can’t be used the way those tools were initially intended.
Instead, you must find a way to make your GitHub Enterprise Server repositories publicly available and enable read access. But this is counterintuitive to GitHub Enterprise Server’s primary goal of security and privacy.
Technically, this is something that you can do, but it’s not something that we can recommend. If you do this, your code can be exposed to the public, which obviously opens up lots of other potential problems for your organization.
Problem #4: Billing
GitHub Enterprise pricing is pretty straightforward. Plans start at $21 per user per month. If you’re on a yearly subscription, you’ll get two months free.
As you know, Enterprise Server plans are a bit more expensive. That’s because you’re incurring additional infrastructure costs beyond GitHub for the on-premises installation and management.
With this in mind, you can’t just stop those costs simultaneously with the Enterprise Cloud migration. There will be some overlap between the two plans, meaning your GitHub costs will double, and you’ll still need to maintain your infrastructure for Enterprise Server.
Assuming you want to eliminate the Enterprise Server completely and strictly stick with the Enterprise Cloud post-migration, you’ll be able to do this down the road. But in the short term, you’ll definitely want to keep the server up and running to ensure a smooth transition.
You could potentially discuss some type of custom enterprise rate with a GitHub sales rep for holding two plans. But that’s not guaranteed.
Logistically, this isn’t a problem that will prevent you from completing this process. But you should definitely be aware of the costs from a budget standpoint.
If you have any questions, don’t hesitate to ask a sales rep. This is the only way to truly understand how you’ll be billed during the transition, for the short term, and for the long run.
