jalalhejazi / gh-gei

GitHub Enterprise Importer CLI

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 as a cross-platform console application to simplify customizing your migration experience.

GEI is in a public beta for GitHub Enterprise Cloud.

Using the GEI CLI

There are 2 separate CLIs that we ship:

• gh gei - Intended for running migrations from anywhere supported to GitHub.
• ado2gh - Extends the basic migration support in gh gei to include extra commands such as re-wiring Azure Pipelines and configure Azure Boards integration post-migration.

To use ado2gh download the latest version from the Releases in this repo.

To use gh gei first install the latest GitHub CLI, then run the command

gh extension install github/gh-gei

We update the gei extension frequently, to ensure you're using the latest version run this command on a regular basis:

gh extension upgrade github/gh-gei

To see the available commands and options run:

ado2gh --help

gh gei --help

GitHub to GitHub Usage (GHEC -> GHEC)

1. Create Personal Access Tokens with access to the source GitHub org, and the target GitHub org (for more details on scopes needed refer to our official documentation).

2. Set the GH_SOURCE_PAT and GH_PAT environment variables.

3. Run the generate-script command to generate a migration script.

gh gei generate-script --github-source-org ORGNAME --github-target-org ORGNAME

4. The previous command will have created a migrate.ps1 script. Review the steps in the generated script and tweak if necessary.

5. The migrate.ps1 script requires powershell to run. If not already installed see the install instructions to install powershell on Windows, Linux, or Mac. Then run the script.

Refer to the official documentation for more details (and differences when migrating from GHES or to GHAE).

Azure DevOps to GitHub Usage

1. Create Personal Access Tokens with access to the Azure DevOps org, and the GitHub org (for more details on scopes needed refer to our official documentation).

2. Set the ADO_PAT and GH_PAT environment variables.

3. Run the generate-script command to generate a migration script.

ado2gh generate-script --ado-org ORGNAME --github-org ORGNAME --all

4. The previous command will have created a migrate.ps1 script. Review the steps in the generated script and tweak if necessary.

5. The migrate.ps1 script requires powershell to run. If not already installed see the install instructions to install powershell on Windows, Linux, or Mac. Then run the script.

Refer to the official documentation for more details.

Quick Start Videos

You'll find videos below to help you quickly get started with the GEI CLI. Be sure to pick the videos relevant to your migration scenario.

NOTE: We don't update these videos as often as we update the CLI, so they may not exactly match the functionality in the latest release of this CLI.

Migrating from Azure DevOps to GitHub

Video guides below will help you get started with your first migration. Then help you build up to orchestrating a complete end-to-end production migration.

• 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

Contributions

See Contributing for more info on how to get involved.