GitHub Enterprise Importer (GEI)

I have spent a lot of time over the last year migrating Repos from Azure DevOps to GitHub, and also between one GitHub Org/Enterprise to another.

Therefore, I thought I would write a series of articles about my experience with the migration tool I’ve been using, GitHub Enterprise Importer.

Disclaimer: This is NOT about the benefits of “Azure DevOps” over “GitHub” or vice versa. Both are great tools with different strengths, that work very well together.

Part 1 — Setup and Log Files

The GitHub Enterprise Importer is a command line tool written by GitHub to make it easier for us to migrate existing repos to GitHub from other tools like Azure DevOps and Bitbucket and even from one GitHub product to another.

This first article is more of an appendix for articles yet to be written. I will refer back to this article from future articles on the subject. This will become a bit of a pre-requisites document for using the GitHub Enterprise Importer tool set.

What you need to install/setup.

1. GitHub CLI — GitHub on the command line.

#Windows
choco install gh

#macOS
brew install gh

2. GitHub Enterprise Importer (gei) - This is implemented as an extension to the GitHub CLI.

• To migrate between GitHub products, install the gh-gei extension

gh extension install github/gh-gei

• To migrate from Azure DevOps, install the gh-ado2gh extension

gh extension install github/gh-ado2gh 

These command line tools use Personal Access Token’s to authenticate with GitHub and Azure DevOps. I found the easiest thing to do is to create a PAT for each product (The links on the product names takes you to instructions for creating a PAT) and set them in the environment where you will run your scripts. Like this:

$ENV:GH_PAT="ghp_myghpat"
$ENV:ADO_PAT="myadopat"

Pipelines: Are you going to be migrating Azure Repos are associated to Azure pipelines? If so, and you want the migrated GitHub Repo to continue to use those Azure Pipelines you’ll want to connect your Azure DevOps Team Project with your GitHub Organization using the Azure Pipelines GitHub application.

In GitHub Marketplace find and install the Azure Pipelines GitHub application into your GitHub organization.

Then create a service connection to it from your Azure DevOps Team Project.

1. In your Azure DevOps Team Project open Project Settings and select Service Connections under pipelines.
2. Click Create new service connection.
3. From the list of service connections select GitHub and click next at the bottom of the dialogue.

4. Fill in the information based on how you want to authenticate.

Note: If you have repos in multiple Team Projects being migrated to one Org in GitHub, you may want to read this article: Azure Pipelines Shared Service Connections to GitHub.

Log Files

As a test of your setup try this.

gh ado2gh generate-script --github-org "My_GitHub_Org" --ado-org "My_ADO_Org" --ado-team-project "My_TeamProject" --sequential --all 

This will generate a script called migrate.ps1 plus two log files.

Every command you run will generate two log files. They will end up looking like this. octoshift was the ame of the tools when I started using it

20221208153329.octoshift.log

20221208153329.octoshift.verbose.log

To get more information in the verbose log, starting in version 0.23 they added a check for an environment variable GEI_DEBUG_MODE. When set to true additional data will be added to the verbose log.

$ENV:GEI_DEBUG_MODE="true"

Over the next few articles, I am going to dive into the various commands and what they do.