Managing access for a migration between products

To protect your data, enforces specific access requirements to use Enterprise Importer. These requirements vary based on the task you are trying to perform. To prevent errors, you should review this article carefully and verify that you meet all of the requirements for the task you want to complete.

To run a migration, you need sufficient access to both the source and the destination for your migration.

The source is the organization on .com or Enterprise Server from which you want to migrate data.

The destination can be:

• An organization account on .com or GHE.com, if you're migrating repositories
• An enterprise account on .com or GHE.com, if you're migrating an entire organization

To have sufficient access for the migration, for both the source and the destination, you need the following things.

• A required role in the organization or enterprise account
• A personal access token that can access the organization or enterprise account
  • The personal access token must have all the required scopes, which depend on your role and the task you want to complete.
  • If the source or destination uses SAML single sign-on for .com, you must authorize the personal access token for SSO.

Additionally, if you use IP allow lists with the source or destination, you may need to configure the allow lists to allow access by Enterprise Importer.

If you're migrating from Enterprise Server 3.8 or higher for the first time, you also need someone with access to the Management Console to set up blob storage for your Enterprise Server instance.

To remove the need for organization owners to complete migrations, includes a distinct role for using Enterprise Importer.

Granting the migrator role allows you to designate other teams or individuals to handle your migrations.

• You can only grant the migrator role for an organization on .com or GHE.com.
• You can grant the migrator role to an individual user or a team. We strongly recommend that you assign the migrator role to a team. Then, you can further customize who can run a migration by adjusting team membership. See Adding organization members to a team or Removing organization members from a team.
• The migrator must use a personal access token that meets all the requirements for running migrations.

To grant the migrator role, see Granting the migrator role.

For the source and destination of the migration, different roles are required for different tasks.

The following table lists which roles can perform which tasks.

The following table lists which roles can perform which tasks.

To run a migration, you need a personal access token that can access the destination organization (for repository migrations) or enterprise account (for organization migrations). You also need another personal access token that can access the source organization.

For other tasks, such as downloading a migration log, you only need one personal access token that can access the target of the operation.

The scopes that are required for your personal access token (classic) depend on your role and the task you want to complete.

To allow someone other than an organization owner to run a repository migration or download migration logs, you can grant the migrator role to a user or team. For more information, see About the migrator role.

You can grant the migrator role using either the GEI extension of the CLI or the GraphQL API.

• Granting the migrator role with the GEI extension
• Granting the migrator role with the GraphQL API

To grant the migrator role using the CLI, you must have installed the GEI extension of the CLI. For more information, see Migrating repositories from .com to Enterprise Cloud.

1. On .com, create and record a personal access token that meets all the requirements for granting the migrator role. For more information, see Creating a personal access token for Enterprise Importer.

2. Set the personal access token as an environment variable, replacing TOKEN in the commands below with the personal access token you recorded above.

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

     Shell

     export GH_PAT="TOKEN"
     

   • If you're using PowerShell, use the $env command.

     Shell

     $env:GH_PAT="TOKEN"
     

3. Use the gh gei grant-migrator-role command, replacing ORGANIZATION with the organization you want to grant the migrator role for, ACTOR with the user or team name, and TYPE with USER or TEAM.

   Shell

   gh gei grant-migrator-role ---org ORGANIZATION --actor ACTOR --actor-type TYPE
   

   Note

   If you're the granting the migrator role for GHE.com, you must also include the target API URL for your enterprise's subdomain. For example: --target-api-url https://api.octocorp.ghe.com.

You can use the grantMigratorRole GraphQL mutation to assign the migrator role and the revokeMigratorRole mutation to revoke the migrator role.

You must use a personal access token (PAT) that meets all access requirements. For more information, see the Required scopes for personal access tokens.

This GraphQL mutation sets the migration role.

mutation grantMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  grantMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}

This mutation removes the migrator role.

mutation revokeMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  revokeMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}

1. Verify that you have a sufficient role for the task you want to complete. For more information, see Required roles.
2. Create a personal access token (classic), making sure to grant all the scopes required for the task you want to complete. You can only use a personal access token (classic), not a fine-grained personal access token. For more information, Managing your personal access tokens and Required scopes for personal access token.
3. If SAML single sign-on is enforced for the organization(s) you need to access, authorize the personal access token for SSO. For more information, see Authorizing a personal access token for use with SAML single sign-on.

If the source or destination of your migration uses an IP allow list (either 's IP allow list feature or your identity provider's (IdP) IP allow list restrictions, such as Azure CAP), you need to configure IP allow lists on . See Managing allowed IP addresses for your organization and Restricting network traffic to your enterprise with an IP allow list.

• If you use 's IP allow list feature, you must add the IP ranges below to the allow list for the source and/or destination organizations.
• If you use your IdP's IP allow list to restrict access to your enterprise on , you should disable these restrictions in your enterprise account settings until after your migration is complete.

The IP ranges vary depending on whether the destination of your migration is .com or GHE.com.

If the source of your migration is Enterprise Server, you do not need to add any IP ranges to your firewall configuration or the IP allow list on your Enterprise Server instance. However, depending on the setup of your blob storage provider, you may need to update your blob storage provider's configuration to allow access to the IP ranges below.

You'll need to add the following IP ranges to your IP allow list(s):

• 192.30.252.0/22
• 185.199.108.0/22
• 140.82.112.0/20
• 143.55.64.0/20
• 40.71.233.224/28
• 2a0a:a440::/29
• 2606:50c0::/32
• 20.125.12.8/29 (active from 00:00 UTC on November 8, 2023)

You can get an up-to-date list of IP ranges used by Enterprise Importer at any time with the "Get meta information" endpoint of the REST API.

The _enterprise_importer key in the response contains a list of IP ranges used for migrations.

For more information, see REST API endpoints for meta data.

You must allow:

• Ranges required for everyone
• Additional ranges that depend on your data residency region

For the ranges to add, see Network details for GHE.com.

In addition, if you are migrating from Enterprise Server and using a blob storage account with firewall rules:

• You must allow access to the egress IP ranges for GHE.com. See Network details for GHE.com.
• If you are using Azure Blob Storage you may need to perform some additional network configuration. This may occur if your Azure Blob Storage happens to be located in the same region as the Enterprise Importer service's compute. Please contact Support.

• Roles in an organization