Migrating your repository with Enterprise Live Migrations

Prerequisites

Make sure you're ready for your migration. See Preparing for your live migration from GitHub Enterprise Server to GHE.com.

1. Create access tokens

You must authenticate with a personal access token (classic) for both the source and destination of the migration. For detailed instructions, see Managing your personal access tokens.

Make a note of both tokens, as you will need them in the next step.

1. Create a personal access token (classic) on GitHub Enterprise Server with the following scopes.

   • repo
   • admin:org
   • admin:repo_hook
   • admin:org_hook

2. Create a personal access token (classic) on GHE.com with the following scopes.

   • repo
   • workflow
   • admin:org
   • admin:repo_hook
   • admin:enterprise

3. If single sign-on is enforced on the target organization on GHE.com, authorize the GHE.com token.

2. Configure GitHub Enterprise Server

You must set some configuration on the GitHub Enterprise Server instance before performing a migration. These configuration values apply to all ELM migrations. Developers on GitHub Enterprise Server may experience a brief downtime when you apply the new configuration.

1. Access the GitHub Enterprise Server administrative shell over SSH. See Accessing the administrative shell (SSH).

2. Set the following configuration variables with ghe-config.

   For example: ghe-config app.elm-exporter.enabled true

   Variable	Set this to...
   app.elm-exporter.enabled	true
   app.elm.internal-webhooks-enabled	true
   app.elm-exporter.webhooks-loopback-address-enabled	true
   secrets.elm-exporter.migration-target-url	The API URL for your destination enterprise (for example: https://api.octocorp.ghe.com). Do not include a trailing slash at the end of the URL.
   secrets.elm-exporter.migration-target-token	The access token you created for GHE.com.
   secrets.elm-exporter.source-token	The access token you created for GitHub Enterprise Server.
   secrets.elm-exporter.source-user	The username associated with the GitHub Enterprise Server token (for example: ghe-admin).
   app.migrations.enabled	If you don't already have migrations enabled on the instance, you must set this to true.

3. Apply the configuration.

   Shell

   ghe-config-apply
   

3. Set required environment variables

When the configuration has been applied, and before starting a migration, set required environment variables. For example:

export API_URL='http://localhost:1738'

Any of these values can also be provided as CLI flags on any elm command, which will take priority over the variables. For example: --api-url http://localhost:1738.

4. Create a migration

Create a new migration by specifying the source and target repository details. --pat-name must be set to system-pat as a static value. The other values are placeholders specific to your environment.

elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO \
  --target-api GHEC-API-URL \
  --pat-name system-pat

elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO \
  --target-api GHEC-API-URL \
  --pat-name system-pat

For example:

elm migration create \
  --source-org my-ghes-org \
  --source-repo my-ghes-repo \
  --target-org my-dr-org \
  --target-repo my-dr-repo \
  --target-api $MIGRATION_TARGET_URL \
  --pat-name system-pat

Optional flags:

• --start: If you're ready to start the migration immediately.
• --target-visibility: Migrated repositories are created with internal visibility by default, but you can specify private.

Save the migration ID

You should see a response like the following:

{
  "migrationId": "2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9",
  "expiresAt":