Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-07-09. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Migrating repositories from GitHub.com to GitHub Enterprise Cloud

You can migrate repositories from GitHub.com to GitHub Enterprise Cloud, using the GitHub CLI or the GraphQL API.

Tool navigation

About repository migrations with GitHub Enterprise Importer

You can run your migration with either the GitHub CLI or the API.

The GitHub CLI simplifies the migration process and is recommended for most customers. Advanced customers with heavy customization needs can use the API to build their own integrations with GitHub Enterprise Importer.

To see instructions for using the API, use the tool switcher at the top of the page.

Prerequisites

  • We strongly recommend that you perform a trial run of your migration and complete your production migration soon after. To learn more about trial runs, see "Overview of a migration between GitHub products."
  • Ensure you understand the data that will be migrated and the known support limitations of the Importer. For more information, see "About migrations between GitHub products."
  • While not required, we recommend halting work during your production migration. The Importer doesn't support delta migrations, so any changes that happen during the migration will not migrate. If you choose not to halt work during your production migration, you'll need to manually migrate these changes.
  • In both the source and destination organization, you must be either an organization owner or be granted the migrator role. For more information, see "Managing access for a migration between GitHub products."

Step 1: Install the GEI extension of the GitHub CLI

If this is your first migration, you'll need to install the GEI extension of the GitHub CLI. For more information about the GitHub CLI, see "About GitHub CLI."

Alternatively, you can download a standalone binary from the releases page for the github/gh-gei repository. You can run the binary directly, without the gh prefix.

  1. Install the GitHub CLI. For installation instructions for GitHub CLI, see the GitHub CLI repository.

    Note: You need version 2.4.0 or newer of GitHub CLI. You can check the version you have installed with the gh --version command.

  2. Install the GEI extension.

    Shell
    gh extension install github/gh-gei
    

Any time you need help with the GEI extension, you can use the --help flag with a command. For example, gh gei --help will list all the available commands, and gh gei migrate-repo --help will list all the options available for the migrate-repo command.

Step 2: Update the GEI extension of the GitHub CLI

The GEI extension is updated weekly. To make sure you're using the latest version, update the extension.

gh extension upgrade github/gh-gei

Step 3: Set environment variables

Before you can use the GEI extension to migrate to GitHub Enterprise Cloud, you must create personal access tokens that can access the source and destination organizations, then set the personal access tokens as environment variables.

  1. Create and record a personal access token that will authenticate for the destination organization on GitHub Enterprise Cloud, making sure that the token meets all requirements. For more information, see "Managing access for a migration between GitHub products."

  2. Create and record a personal access token that will authenticate for the source organization, making sure that this token also meets all of the same requirements.

  3. Set environment variables for the personal access tokens, replacing TOKEN in the commands below with the personal access tokens you recorded above. Use GH_PAT for the destination organization and GH_SOURCE_PAT for the source organization.

    • If you're using Terminal, use the export command.

      Shell
      export GH_PAT="TOKEN"
      export GH_SOURCE_PAT="TOKEN"
      
    • If you're using PowerShell, use the $env command.

      Shell
      $env:GH_PAT="TOKEN"
      $env:GH_SOURCE_PAT="TOKEN"
      

Step 4: Generate a migration script

If you want to migrate multiple repositories to GitHub Enterprise Cloud at once, use the GitHub CLI to generate a migration script. The resulting script will contain a list of migration commands, one per repository.

Note: Generating a script outputs a PowerShell script. If you're using Terminal, you will need to output the script with the .ps1 file extension and install PowerShell for either Mac or Linux to run it.

If you want to migrate a single repository, skip to the next step.

Generating a migration script

To generate a migration script, run the gh gei generate-script command.

Shell
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME

If you want the script to download the migration log for each migrated repository, add the --download-migration-logs flag. For more information about migration logs, see "Accessing your migration logs for GitHub Enterprise Importer."

Replace the placeholders in the command above with the following values.

PlaceholderValue
SOURCEName of the source organization
DESTINATIONName of the destination organization
FILENAMEA filename for the resulting migration script

If you're using Terminal, use a .ps1 file extension as the generated script requires PowerShell to run. You can install PowerShell for Mac or Linux.

If you downloaded GEI as a standalone binary rather than as an extension for the GitHub CLI, you will need to update your generated script to run the binary instead of gh gei.

Reviewing the migration script

After you generate the script, review the file and, optionally, edit the script.

  • If there are any repositories you don't want to migrate, delete or comment out the corresponding lines.
  • If you want any repositories to have a different name in the destination organization, update the value for the corresponding --target-repo flag.

Note: If your repository has more than 10 GB of releases data, releases cannot be migrated. Use the --skip-releases flag to migrate the repository without releases.

If you downloaded GEI as a standalone binary rather than as an extension for the GitHub CLI, you will need to update your generated script to run the binary instead of gh gei.

Step 5: Migrate repositories

You can migrate multiple repositories with a migration script or a single repository with the gh gei migrate-repo command.

Migrate multiple repositories

To migrate multiple repositories, run the script you generated above. Replace FILENAME in the commands below with the filename you provided when generating the script.

  • If you're using Terminal, use ./.

    Shell
    ./FILENAME
    
  • If you're using PowerShell, use .\.

    Shell
    .\FILENAME
    

Migrate a single repository

To migrate a single repository, use the gh gei migrate-repo command.

Shell
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME

Note: If your repository has more than 10 GB of releases data, releases cannot be migrated. Use the --skip-releases flag to migrate the repository without releases.

Replace the placeholders in the command above with the following values.

PlaceholderValue
SOURCEName of the source organization
CURRENT-NAMEThe name of the repository you want to migrate
DESTINATIONName of the destination organization
NEW-NAMEThe name you want the migrated repository to have

If you want to cancel a migration, use the abort-migration command, replacing MIGRATION-ID with the ID returned from migrate-repo.

Shell
gh gei abort-migration --migration-id MIGRATION-ID

Step 6: Validate your migration and check the error log

When your migration is complete, we recommend reviewing your migration log. For more information, see "Accessing your migration logs for GitHub Enterprise Importer."

We recommend that you review your migrated repositories for a soundness check.

Press alt+up to activate