The GitHub Enterprise Importer (GEI, formerly Octoshift) is a highly customizable API-first migration offering designed to help you move your enterprise to GitHub Enterprise Cloud. The GEI-CLI wraps the GEI APIs to simplify customizing your migration experience.

GEI is in a private preview for GitHub Enterprise Cloud. It needs to be enabled before using this CLI. Please reach out to GitHub Sales to enquire about getting into the private beta.

This version of the GEI-CLI is informally maintained by GitHub. However, this is not a supported GitHub product. Customers leveraging these tools must understand that any support must come through a paid GitHub Expert Services engagement.

GEI-CLI is continuing to expand what it can support. However, it supports the following scenarios at present:

• Azure DevOps -> GitHub Enterprise Cloud migrations
• GitHub Enterprise Cloud -> GitHub Enterprise Cloud migrations

Learn more about what exactly is migrated and any limitations in the GEI documentation.

Check out the below videos for getting quickly getting started with the GEI-CLI.

• Running your first few migrations: https://www.youtube.com/watch?v=yfnXbwtXY80
• Orchestrating an end-to-end production migration: https://www.youtube.com/watch?v=AtFB-U1Og4c

GEI-CLI is a cross-platform .NET Core console application. Execute the executable without any parameters to learn about the options. General usage will use the generate-script option to create a script that can be used to migrate all repositories from an Azure DevOps org and re-wire Azure Boards and Azure Pipelines connections.

ado2gh
  Migrates Azure DevOps repos to GitHub
Usage:
  ado2gh [options] [command]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  generate-script
  rewire-pipeline
  integrate-boards
  share-service-connection
  disable-ado-repo
  lock-ado-repo             Makes the ADO repo read-only for all users. It does this by adding Deny permissions for the Project Valid Users group on the repo.
  configure-auto-link
  create-team               Creates a GitHub team and optionally links it to an IdP group.
  add-team-to-repo
  migrate-repo

To generate a script, you'll need to set an ADO_PAT as an environment variable. Performing any of the commands that touch GitHub will need the GH_PAT environment variable.

Covering running a migration from Azure DevOps to GitHub.com.

Navigate to the Releases for this repository and grab the latest release for your local operating system. Note: ado2gh is for Azure DevOps -> GitHub migrations, gei is for GitHub -> GitHub migrations. Once you have downloaded the Release, you need to extract it to your local machine. Note you will want to place the octoshift executable somewhere easy to reference or add to your path.

• Linux add folder to path
• Powershell add folder to path

Once you have pathed the tooling, you will need to set 2 environment variables.

• One will be called GH_PAT and will be your GitHub Personal Access Token
• The other will be called ADO_PAT and will be your Azure DevOps Access Token

The scope needed for each token will depend on what command(s) you want run. See the scenarios below to ensure you have properly scoped personal access tokens. It's recommended that you pick the scenario which fits the needs of everything you want to do as part of migrating.

Create a GitHub and Azure DevOps personal access tokens with the scope defined in GEI's documentation. This will allow you to run these commands:

• generate-script (--repos-only)
• migrate-repo
• grant/revoke-migrator-role
• create-team
• add-team-to-repo
• configure-autolink

In order to use the following pre & post migration commands:

• lock-ado-repo
• disable-ado-repo
• generate script (without the --repos-only flag)

You will need to include these additional scopes for your Azure DevOps personal access token in addition to the ones listed in GEI's documentation:

• Service Connection (Read)
• Build (Read & execute)
• Security (Manage)
• Code (Read, write, and manage)

If you want to re-connect an Azure Pipline or Board to the migrated repo then you'll need your ADO personal access token to be full access.

At this point, you can now begin to run and test the import process.

Once you have configured the octoshift(gh-gei) command-line tool and environment variables for the person access tokens, you can run the command-line tool and see all available options.

The first step you will want to run is generate-script to help outline all commands to migrate an entire Azure Project This command will generate a octoshift.sh file in the local folder. You will want to open it with an editor tool as it can be quite large. It's recommended that you include the --repos-only flag the first time. Tools like Atom, VSCode, or NotePad++ are great ways to see the data. As you can see from the data, it builds out the command-line options one after another to migrate all repositories, lock repositories, create teams, etc.

You can then use this as a guide to pick and choose which commands you would like to run.

See Contributing for more info on how to get involved.