ghe‐migrate - elliottcarlson/ghe GitHub Wiki

This utility assists in automating the migration process of an organization from github.com to the hosted Github Enterprise server.

GHE> migrate -h
usage: ghe-migrate.py [-h] [-repos REPOS] [-file REPOS] [-all] [-resolve-all]
                      [-batch INT] [-skip INT] [-ghe-host HOST]
                      [-ghe-ssh-port PORT] [-ghe-ssh-user USER]
                      [-ghe-user USER] [-ghe-token TOKEN] [-gh-token TOKEN]
                      source [dest]

Tool to perform GitHub to GitHub Enterprise migrations.

positional arguments:
  source              the organization to migrate
  dest                the destination organization

optional arguments:
  -h, --help          show this help message and exit
  -repos REPOS        comma separated list of repos
  -file REPOS         file with one repo per line
  -all                use all repos from organization
  -debug        attempt to automatically resolve all migration conflicts
  -batch INT          number of repos to process per batch (default: 100)
  -skip INT           number of repos to skip from the start (default: 0)
  -ghe-host HOST      the hostname to your GitHub Enterprise server (default:
                      value from `ghe-host` environment variable)
  -ghe-ssh-port PORT  the port to your GitHub Enterprise SSH server (default:
                      122, or value from `ghe-ssh-port` environment variable)
  -ghe-ssh-user USER  the user to use for SSH access to your GitHub Enterprise
                      server (default: value from `ghe-ssh-user` environment
                      variable)
  -ghe-user USER      GitHub Enterprise admin level username on the
                      destination GHE instance (default: value from `ghe-
                      user` environment variable)
  -ghe-token TOKEN    GitHub Enterprise access token for user set with -ghe-
                      user (default: value from `ghe-token` environment
                      variable)
  -gh-token TOKEN     GitHub.com access token for an account with admin
                      priveleges on source organization (default: value from
                      `gh-token` environment variable)

You must use one of -repos, -file or -all.
GHE>

When starting a migration, you must select one or more repositories that will be migrated over. This can be selected in one of three ways.

-repos [REPOS] allows you to specify a comma separated list of repository names, without spaces. -file [FILENAME] allows you to specify a file that contains a list of repository names, one per newline. -all allows you to automatically discover and migrate all repositories that were listed in the source organization

To prevent blocking on the Github.com side when initiating a migration, repositories need to be batched in groups. The -batch [INT] argument allows you to optionally override the default batch size of 100 repositories. This can be useful if there is a larger repository that is causing the process to fail. Ideally, you would only want to override the batch limit to a lower number -- it is not advisable to attempt to perform larger batches than 100.

If, for whatever reason, the process were to fail mid-migration, you can utilize the skip functionality to ignore the first X repositories from being migrated. For example, if you were migrating 700 repositories, and it failed after the 343rd one, you could reissue the migration command with -skip 343 and it will continue from there.

All of the parameters starting with -ghe- are required parameters that give the script the necessary access to connect to both Github.com and Github Enterprise. If you are using the ghe command line wrapper, this information will be passed in automatically from the MacOSX keyring, if you have set the information up accordingly.

Migrations will generally have conflicts that it will request assistance in resolving. This is done by displaying a CSV that is opened in the default console text editor. Saving any changes to this file will complete the conflicts. For more information on the possible conflict resolution syntax, please see https://help.github.com/enterprise/2.10/admin/guides/migrations/reviewing-migration-conflicts/

Most conflicts will be auto-resolved, and only when an issue needs your attention will you be prompted.

Before performing your migration; please ensure the following:

• The GitHub.com access token belongs to an account that has been made an administrator of the source organization
• That you have added your SSH key to GitHub Enterprise, and tested a successful SSH connection
• That ssh-agent is running, and that your SSH key has been added to the agent, e.g. ssh-add ~/.ssh/id_rsa

Sample migration session that will migrate all the repositories in the github.com organization elliottcarlson-test-org11 to a new organization on GitHub Enterprise named elliott-org-migration-test.

GHE> migrate -all elliottcarlson-test-org11 elliott-org-migration-test
Retrieving repos from elliottcarlson-test-org11.
Found 2 repos in elliottcarlson-test-org11.
Requesting migration from GitHub for 2 repos.
Migration archive created.
Downloading migration archive.
Archive downloaded.
Preparing downloaded archive for migration.
Migration GUID: 0e56007c-6544-11e7-9de7-157ddd697b44
Mapping source organization to destination organization.
Checking for conflicts.
Press Enter key to manually edit conflicts...
[... Vim opens here to allow editing of the conflicts ...]
Attempting to resolve conflicts.
Importing archive data in to GHE.
Migration complete.
GHE>