Migration d’organisations de .com vers Enterprise Cloud

About organization migrations with Enterprise Importer

Migrations to Enterprise Cloud include migrations between accounts on .com and, if you're adopting data residency, migrations to your enterprise's subdomain of GHE.com.

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

The 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 Enterprise Importer.

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

To see instructions for using the CLI, 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 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 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.
For the source organization, you must be an organization owner or have the migrator role. For more information, see Managing access for a migration between products.
For the destination enterprise account, you must be an enterprise owner.

Step 0: Get ready to use the GraphQL API

To make GraphQL queries, you'll need to write your own scripts or use an HTTP client like Insomnia.

To learn more about getting started with the GraphQL API, including how to authenticate, see Forming calls with GraphQL.

You will send all GraphQL queries to the destination of your migration. If you're migrating to Enterprise Cloud with data residency, make sure to send queries to the endpoint for your enterprise's subdomain of GHE.com.

Step 1: Get the enterprise ID for your migration destination

As an enterprise owner in .com, use the following query to return the ID for the enterprise account you want to own the migrated organization. You'll need the enterprise ID to identify your migration destination.

query(
  $slug: String!
){
  enterprise (slug: $slug)
  {
    slug
    id
  }
}

Query variable	Description
`slug`	The slug for your enterprise account, which you can identify by looking at the URL for your enterprise, `https://.com/enterprises/SLUG` or `https://SLUG.ghe.com`.

Step 2: Start your organization migration

When you start a migration, a single organization and its accompanying data migrates into a brand new organization within the destination enterprise that you identify.

mutation startOrganizationMigration (
  $sourceOrgUrl: URI!,
  $targetOrgName: String!,
  $targetEnterpriseId: ID!,
  $sourceAccessToken: String!,
	$targetAccessToken: String!
){
  startOrganizationMigration( input: {
    sourceOrgUrl: $sourceOrgUrl,
    targetOrgName: $targetOrgName,
    targetEnterpriseId: $targetEnterpriseId,
    sourceAccessToken: $sourceAccessToken,
		targetAccessToken: $targetAccessToken
  }) {
    orgMigration {
      id
    }
  }
}

Query variable	Description
`sourceOrgUrl`	The URL of the source organization, such as `https://.com/octo-org`.
`targetOrgName`	The name you want the new organization to have. Cannot be shared by another organization on your destination platform.
`targetEnterpriseId`	The ID of the enterprise that you want to create the new organization in, returned by step 2.
`sourceAccessToken`	Your personal access token (classic) for the source organization. For requirements, see Managing access for a migration between products.
`targetAccessToken`	Your personal access token (classic) for the destination enterprise.

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

Step 3: Check the status of your migration

To detect any migration failures and ensure your migration is working, you can query the OrganizationMigration(s) that you have created to see the migration status using the getMigration query.

The query will return with a status to let you know if the migration is queued, in progress, failed, or completed, plus information about how many repositories are waiting to be migrated. If your migration failed, the Importer will provide a reason for the failure.

query (
  $id: ID!
){
  node( id: $id ) {
    ... on OrganizationMigration {
      id
			sourceOrgUrl
			targetOrgName
      state
      failure_reason
      remaining_repositories_count
      total_repositories_count
    }
  }
}

Query variable	Description
`id`	The `id` of your migration.

Step 1: Install the GEI extension of the CLI

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

Install the CLI. For installation instructions for CLI, see the CLI repository.
Remarque
You need version 2.4.0 or newer of CLI. You can check the version you have installed with the gh --version command.

Install the GEI extension.

Shell

gh extension install /gh-gei

gh extension install /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 CLI

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

gh extension upgrade /gh-gei

Step 3: Set environment variables

Before you can use the GEI extension to migrate to Enterprise Cloud, you must create personal access tokens (classic) that can access the source organization and destination enterprise, then set the personal access tokens (classic) as environment variables.

Create and record a personal access token that meets all the requirements to authenticate for the source organization for organization migrations. For more information, see Managing access for a migration between products.
Create and record a personal access token (classic) that meets all the requirements to authenticate for the destination enterprise for organization migrations.
Set environment variables for the personal access tokens (classic), replacing TOKEN in the commands below with the personal access tokens (classic) you recorded above. Use GH_PAT for the destination enterprise 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"
```
```
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"
```
```
$env:GH_PAT="TOKEN"
$env:GH_SOURCE_PAT="TOKEN"
```
If you're migrating to Enterprise Cloud with data residency, for convenience, set an environment variable for the base API URL for your enterprise.
- If you're using Terminal, use the export command.
  Shell
```
export TARGET_API_URL="https://api.octocorp.ghe.com"
```
```
export TARGET_API_URL="https://api.octocorp.ghe.com"
```
- If you're using PowerShell, use the $env command.
  Shell
```
$env:TARGET_API_URL="https://api.octocorp.ghe.com"
```
```
$env:TARGET_API_URL="https://api.octocorp.ghe.com"
```
You'll use this variable with the --target-api-url option in commands you run with the CLI.

Step 4: Migrate your organization

To migrate an organization, use the gh gei migrate-org command.

Shell

gh gei migrate-org ---source-org SOURCE ---target-org DESTINATION ---target-enterprise ENTERPRISE

gh gei migrate-org ---source-org SOURCE ---target-org DESTINATION ---target-enterprise ENTERPRISE

Remarque

If you're migrating to GHE.com, add --target-api-url TARGET-API-URL, where TARGET-API-URL is the base API URL for your enterprise's subdomain. For example: https://api.octocorp.ghe.com.

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

Placeholder	Value
SOURCE	Name of the source organization
DESTINATION	The name you want the new organization to have. Cannot be shared by another organization on your destination platform.
ENTERPRISE	The slug for your destination enterprise, which you can identify by looking at the URL for your enterprise account, `https://.com/enterprises/SLUG` or `https://SLUG.ghe.com`.

Step 5: Validate your migration and check the error log

Step 4: Validate your migration and check the error log

After your migration has finished, we recommend that you check the migration log repository. For more information, see Accessing your migration logs for Enterprise Importer.

Finally, we recommend you perform a soundness check of your organization and migrated repositories.