Skip to main content

This version of GitHub Enterprise Server was discontinued on 2024-03-26. 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.

Managing access for a migration between GitHub products

Before you use GitHub Enterprise Importer, make sure you have appropriate access to both the source and destination of your migration.

About required access for GitHub Enterprise Importer

To protect your data, GitHub enforces specific access requirements to use GitHub 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 GitHub.com or GitHub Enterprise Server from which you want to migrate data. The destination is either an organization account on GitHub.com, if you're migrating repositories, or an enterprise account on GitHub.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 GitHub.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 GitHub Enterprise Importer.

If you're migrating from GitHub 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 GitHub Enterprise Server instance.

About the migrator role

To remove the need for organization owners to complete migrations, GitHub.com includes a distinct role for using GitHub 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 GitHub.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. For more information about changing team membership, see "Adding organization members to a team" or "Removing organization members from a team."

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

After you grant the migrator role, make sure the migrator uses a personal access token that meets all the requirements for running migrations.

Notes:

  • If you're migrating a repository between two organizations on GitHub.com, you can grant the migrator role to the same person or team for both organizations, but you must grant each separately.
  • You cannot grant the migrator role for enterprise accounts. Therefore, you can only run an organization migration if you're an owner of the destination enterprise. However, you can grant the migrator role to that enterprise owner for the source organization.
  • The GitHub CLI does not support granting the migrator role for organizations on GitHub Enterprise Server, so you must be an organization owner of the source organization to migrate repositories from GitHub Enterprise Server.

Required roles

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

Source organization

The following table lists which roles can perform which tasks.

TaskOrganization ownerMigrator
Running a migration
Assigning the migrator role for repository migrations

Destination organization or enterprise

The following table lists which roles can perform which tasks.

TaskEnterprise ownerOrganization ownerMigrator
Migrating organizations to an enterprise
Assigning the migrator role for repository migrations
Migrating repositories to an organization
Downloading a migration log
Reclaiming mannequins

Required scopes for personal access tokens

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 GitHub personal access token depend on your role and the task you want to complete.

Note: You can only use a personal access token, not a fine-grained personal access token. This means that you cannot use GitHub Enterprise Importer if your organization uses the "Restrict personal access tokens from accessing your organizations" policy. For more information, see "Enforcing policies for personal access tokens in your enterprise."

TaskEnterprise ownerOrganization ownerMigrator
Assigning the migrator role for repository migrationsadmin:org
Running a repository migration (destination organization)repo, admin:org, workflowrepo, read:org, workflow
Downloading a migration logrepo, admin:org, workflowrepo, read:org, workflow
Reclaiming mannequinsadmin:org
Running a migration (source organization)read:org, reporead:org, repo
Running an organization migration (destination enterprise)read:enterprise, admin:org, repo, workflow

Granting the migrator role

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 GitHub CLI or the GraphQL API.

Granting the migrator role with the GEI extension

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

  1. On GitHub.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 GitHub 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 --github-org ORGANIZATION --actor ACTOR --actor-type TYPE
    

Granting the migrator role with the GraphQL API

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

grantMigratorRole mutation

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 }
}
Query variableDescription
organizationIdThe ownerId (or organization ID) for your organization, from the GetOrgInfo query.
actorThe team or username who you want to assign the migration role to.
actor_typeSpecify whether the migrator is a USER or TEAM.

revokeMigratorRole mutation

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 }
}

Creating a personal access token for GitHub Enterprise Importer

  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, making sure to grant all the scopes required for the task you want to complete. You can only use a personal access token, 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."

Configuring IP allow lists for migrations

If the source or destination of your migration uses an IP allow list (either GitHub'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 GitHub.com.

  • If you use GitHub's IP allow list feature, you must add the GitHub 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 GitHub.com, you should disable these restrictions in your enterprise account settings until after your migration is complete.

For more information, see "Managing allowed IP addresses for your organization" and "Restricting network traffic to your enterprise with an IP allow list."

If the source of your migration is GitHub Enterprise Server, you do not need to add any GitHub IP ranges to your firewall configuration or the IP allow list on your GitHub 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 GitHub IP ranges below.

Identifying GitHub's IP ranges

You'll need to add the following IP ranges to your IP allowlist(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 GitHub Enterprise Importer at any time with the "Get GitHub meta information" endpoint of the REST API.

The github_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."

Further reading