Migrating repositories from GitHub Enterprise Server to GitHub Enterprise Cloud

If you choose to use the API, you'll need to write your own scripts or use an HTTP client like Insomnia. You can learn more about getting started with GitHub's APIs in "Getting started with the REST API" and "Forming calls with GraphQL."

To migrate your repositories from GitHub Enterprise Server to GitHub Enterprise Cloud with the APIs, you will:

1. Create a personal access token for both the source and destination organization
2. Fetch the ownerId of the destination organization on GitHub Enterprise Cloud
3. Set up a migration source via GitHub.com's GraphQL API to identify where you're migrating from
4. For each repository you want to migrate, repeat these steps.
   • Use the REST API on your GitHub Enterprise Server instance to generate migration archives for your repository
   • Upload your migration archives to a location where they can be accessed by GitHub.com
   • Start your migration using the GraphQL API for GitHub.com, passing in your archive URLs
   • Check the status of your migration via the GraphQL API
   • Validate your migration and check the error log

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

Step 1. Create your personal access token

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 GitHub Enterprise Importer."
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.

Step 2: Get the ownerId for the destination organization

As an organization owner in GitHub Enterprise Cloud, use the GetOrgInfo query to return the ownerId, also called the organization ID, for the organization you want to own the migrated repositories. You'll need the ownerId to identify your migration destination.

GetOrgInfo query

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

Query variable	Description
login	Your organization name.

GetOrgInfo response

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

In this example, MDEyOk9yZ2FuaXphdGlvbjU2MTA= is the organization ID or ownerId, which we'll use in the next step.

Step 3: Set up blob storage

Because many GitHub Enterprise Server instances sit behind firewalls, for GitHub Enterprise Server versions 3.8 or higher, we use blob storage as an intermediate location to store your data that GitHub can access.

You must first set up blob storage with a supported cloud provider, then configure your settings in the Management Console of your GitHub Enterprise Server instance.

Setting up blob storage with a supported cloud provider

The GitHub CLI supports the following blob storage providers:

• Amazon Web Services (AWS) S3
• Azure Blob Storage

Setting up an AWS S3 storage bucket

In AWS, set up a S3 bucket. For more information, see Creating a bucket in the AWS documentation.

You will also need an AWS access key and secret key with read-write access to your bucket.

Setting up an Azure Blob Storage account

In Azure, create a storage account and make a note of your connection string. For more information, see Manage storage account access keys in Microsoft Docs.

Configuring blob storage in the Management Console of your GitHub Enterprise Server instance

After you set up an AWS S3 storage bucket or Azure Blob Storage storage account, configure blob storage in the Management Console of your GitHub Enterprise Server instance. For more information about the Management Console, see "Administering your instance from the Management Console."

1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .
2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.
3. In the " Site admin" sidebar, click Management Console.
4. Log into the Management Console.
5. In the top navigation bar, click Settings.
6. Under Migrations, click Enable GitHub Migrations.
7. Optionally, to import storage settings you configured for GitHub Actions, select Copy Storage settings from Actions. For more information see, "Enabling GitHub Actions with Azure Blob storage" and "Enabling GitHub Actions with Amazon S3 storage."
8. If you do not import storage settings from GitHub Actions, select either Azure Blob Storage or Amazon S3 and fill in the required details.
9. Click Test storage settings.
10. Click Save settings.

Step 4: Set up a migration source in GitHub Enterprise Cloud

You can set up a migration source using the createMigrationSource query. You'll need to supply the ownerId, or organization ID, gathered from the GetOrgInfo query.

Your migration source is your organization on GitHub Enterprise Server.

createMigrationSource mutation

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Query variable	Description
name	A name for your migration source. This name is for your own reference, so you can use any string.
ownerId	The organization ID of your organization on GitHub Enterprise Cloud.
url	The URL for your GitHub Enterprise Server instance. This URL does not need to be accessible from GitHub Enterprise Cloud.

createMigrationSource response

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ",
        "name": "GHES Source",
        "url": "https://my-ghes-hostname.com",
        "type": "GITHUB_ARCHIVE"
      }
    }
  }
}

In this example, MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ is the migration source ID, which we'll use in a later step.

Step 5: Generate migration archives on your GitHub Enterprise Server instance

You will use the REST API to start two "migrations" in GitHub Enterprise Server: one to generate an archive of your repository's Git source, and one to generate an archive of your repository's metadata (such as issues and pull requests).

To generate the Git source archive, make a POST request to https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations, replacing HOSTNAME with the hostname of your GitHub Enterprise Server instance, and ORGANIZATION with your organization's login.

In the body, specify the single repository you want to migrate. Your request will look something like this:

POST /api/v3/orgs/acme-corp/migrations HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Content-Type: application/json
Host: github.acmecorp.net

{
  "repositories": ["repository_to_migrate"],
  "exclude_metadata": true
}

To generate your metadata archive, send a similar request to the same URL with the following body:

{
  "repositories": ["repository_to_migrate"],
  "exclude_git_data": true,
  "exclude_releases": false,
  "exclude_owner_projects": true
}

Each of these two API calls will return a JSON response including the ID of the migration you have started.

HTTP/1.1 201 Created

{
  "id": 123,
  // ...
}

For more information, see "Start an organization migration" in the REST API documentation.

Generating the archives can take a while, depending on the amount of data. You can regularly check the status of the two migrations with the "Get an organization migration status" API until the state of the migration changes to exported.

GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "state": "exported",
  // ...
}

For more information, see "Get an organization migration status" in the REST API documentation.

After the state of a migration moves to exported, you can fetch the migration's URL using the "Download an organization migration archive" API.

GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 302 Found
Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6

The API will return a 302 Found response with a Location header redirecting to the URL where the downloadable archive is located. Download the two files: one for the Git source, and one for the metadata.

For more information, see "Download an organization migration archive" in the REST API documentation.

After both migrations have completed and you have downloaded the archives, you can move to the next step.

Step 6: Upload your migration archives

To import your data into GitHub Enterprise Cloud, you must pass both archives for each repository (Git source and metadata) from your machine to GitHub.com, using our GraphQL API.

If you're using GitHub Enterprise Server 3.7 or lower, you must first generate URLs for the archives that are accessible by GitHub.com. Most customers choose to upload the archives to a cloud provider's blob storage service, such as Amazon S3 or Azure Blob Storage, then generate a short-lived URL for each.

If you're using GitHub Enterprise Server 3.8 or higher, your instance uploads the archives and generates the URLs for you. The Location header in the previous step will return the short-lived URL.

You may need to allowlist GitHub's IP ranges. For more information, see "Managing access for GitHub Enterprise Importer."

Step 7: Start your repository migration

When you start a migration, a single repository and its accompanying data migrates into a brand new GitHub repository that you identify.

If you want to move multiple repositories at once from the same source organization, you can queue multiple migrations. You can run up to 5 repository migrations at the same time.

startRepositoryMigration mutation

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

Query variable	Description
sourceId	Your migration source id returned from the createMigrationSource mutation.
ownerId	The organization ID of your organization on GitHub Enterprise Cloud.
repositoryName	A custom unique repository name not currently used by any of your repositories owned by the organization on GitHub Enterprise Cloud. An error-logging issue will be created in this repository when your migration is complete or has stopped.
continueOnError	Migration setting that allows the migration to continue when encountering errors that don't cause the migration to fail. Must be true or false. We highly recommend setting continueOnError to true so that your migration will continue unless the Importer can't move Git source or the Importer has lost connection and cannot reconnect to complete the migration.
githubPat	The personal access token for your destination organization on GitHub Enterprise Cloud. For personal access token requirements, see "Managing access for GitHub Enterprise Importer."
accessToken	The personal access token for your source.
targetRepoVisibility	The visibility of the new repository. Must be private, public, or internal. If not set, your repository is migrated as private.
gitArchiveUrl	A GitHub Enterprise Cloud-accessible URL for your Git source archive.
metadataArchiveUrl	A GitHub Enterprise Cloud-accessible URL for your metadata archive.
sourceRepositoryUrl	The URL for your repository on your GitHub Enterprise Server instance. This is required, but GitHub Enterprise Cloud will not communicate directly with your GitHub Enterprise Server instance.

In the next step, you'll use the migration ID returned from the startRepositoryMigration mutation to check the migration status.

Step 8: Check the status of your migration

To detect any migration failures and ensure your migration is working, you can check your migration status using the getMigration query. You can also check the status of multiple migrations with getMigrations.

The getMigration query will return with a status to let you know if the migration is queued, in progress, failed, or completed. If your migration failed, the Importer will provide a reason for the failure.

getMigration query

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}

Query variable	Description
id	The id of your migration that the startRepositoryMigration mutation returned.

Step 9: Validate your migration and check the error log

To finish your migration, we recommend that you check the "Migration Log" issue. This issue is created on GitHub in the destination repository.

Finally, we recommend that you review your migrated repositories for a soundness check.

gh extension upgrade github/gh-gei

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"