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 Verwalten deiner persönlichen Zugriffstoken.

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 Auf die Verwaltungsshell (SSH) zugreifen.

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).

3. If you don't already have migrations enabled and blob storage configured on the instance, you can configure them now. You can check your existing settings in in "Migrations" section of the Management Console (HOSTNAME/setup/settings).

   You can use the following default values, which will not introduce any unexpected functionality.

   Shell

   ghe-config app.migrations.enabled true
   

   Shell

   ghe-config secrets.migrations.blob-storage-type local-storage
   

4. 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": "2026-02-11T21:49:33.619162159Z"
}

Export the migrationId as a variable, as you will need it for the next commands. For example:

export MIGRATION_ID='2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9'

5. Start the migration

If you didn't already start the migration, start it now using the migration ID you just saved.

elm migration start --migration-id $MIGRATION_ID

elm migration start --migration-id $MIGRATION_ID

This launches the backfill and live update processes. ELM is now collecting data from the source repository and listening for supported webhook events.

6. Monitor the migration

When the migration has started, you should see a new repository on GHE.com. During the migration, you will see the repository fill with an initial load of data and receive updates as developers continue to work in the source repository.

Run the following command regularly to monitor the migration status. You will see a breakdown of the statuses of the source and target, and information on live data being migrated.

elm migration status --migration-id $MIGRATION_ID

elm migration status --migration-id $MIGRATION_ID

The most important indicator in the response is the status in the combinedState object. When the status reaches COMBINED_STATUS_READY_FOR_CUTOVER, you should be ready to proceed to the next step. However, you will be alerted in the displayMessage if any individual resources failed to migrate, which you may need to investigate.

For example:

  "combinedState":  {
    "status":  "COMBINED_STATUS_READY_FOR_CUTOVER",
    "displayMessage":  "Ready for cutover (1 resources failed)",
    "repositories":  [
      {
        "repositoryNwo":  "new-test-org/my-new-repo",
        "phase":  "REPOSITORY_PHASE_READY_FOR_CUTOVER",
        "displayStatus":  "Ready for cutover (1 failed)"
      }
    ],
    "readyForCutover":  true,
    "cutoverBlockers":  []
  },

Tips:

• If you're running multiple migrations, you can check the status of all of them with elm migration list. This command shows in-progress migrations by default, but you can also filter by --status.
• If you encounter failure statuses that require attention, see Troubleshooting live migrations from GitHub Enterprise Server to GHE.com.

7. Complete the migration

When a migration is ready for cutover, you can complete the migration. The cutover process will lock the source repository, making it permanently unavailable for developers unless an administrator unlocks it.

elm migration cutover-to-destination --migration-id $MIGRATION_ID

elm migration cutover-to-destination --migration-id $MIGRATION_ID

Continue to monitor the migration. When you see the MIGRATION_STATUS_COMPLETED status at the top of the response, the migration is complete, although there are some follow-up tasks to give access to users from GitHub Enterprise Server.

Next steps

Give users access to the new repository and reconcile activity with user accounts. See Completing your live migration from GitHub Enterprise Server to GHE.com.