Managing access for a migration from Azure DevOps

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

En este artículo

About required access for GitHub Enterprise Importer

Para proteger los datos, GitHub aplica requisitos de acceso específicos para usar GitHub Enterprise Importer. Estos requisitos varían en función de la tarea que intentas realizar. Para evitar errores, debes revisar este artículo cuidadosamente y comprobar que cumples todos los requisitos de la tarea que quieres completar.

To migrate a repository from Azure DevOps to GitHub, you need sufficient access to both the source (an organization on Azure DevOps) and the destination (an organization on GitHub). To have sufficient access, you'll need all of the following things.

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

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.

About the migrator role

Para quitar la necesidad de que los propietarios de la organización completen las migraciones, en GitHub se incluye un rol único para usar GitHub Enterprise Importer.

La concesión del rol de migración te permite designar otros equipos o individuos para controlar las migraciones.

  • Solo puedes conceder el rol de migración para una organización en GitHub.com o GHE.com.
  • Puedes conceder el rol de migración a un usuario individual o a un equipo. Se recomienda encarecidamente asignar el rol de migración a un equipo. Después, puedes personalizar aún más quién puede ejecutar una migración si ajustas la pertenencia al equipo. Consulta Agregar miembros de la organización a un equipo o Eliminar de un equipo a miembros de la organización.
  • El responsable de la migración debe usar una instancia de personal access token que cumpla todos los requisitos para ejecutar migraciones.

Advertencia

Cuando se concede el rol de migrador en una organización a un usuario o equipo, se le concede la capacidad de importar o exportar cualquier repositorio de esa organización.

Para conceder el rol de migración, consulta Concesión del rol de migración.

Required roles for GitHub

For the destination organization on GitHub, different roles are required for different tasks.

En la tabla siguiente se enumeran qué tareas pueden realizar qué roles.

TareaPropietario de la organizaciónResponsable de la migración
Asignación del rol de migración para las migraciones de repositorio
Ejecución de una migración de repositorio
Descarga de un registro de migración
Reclamación de maniquíes

Required scopes for personal access tokens

To run a migration, you need one personal access token that can access the destination organization on GitHub, and another personal access token that can access the source organization on Azure DevOps.

For other tasks, such as downloading a migration log, you only need one personal access token that can access the destination organization on GitHub.

Personal access tokens for GitHub

Los ámbitos necesarios para GitHub personal access token (classic) dependen de tu rol y de la tarea que quieras completar.

Nota:

Solo puedes usar un personal access token (classic), no un fine-grained personal access token. Esto significa que no puedes usar GitHub Enterprise Importer si tu organización usa la directiva "Restrict personal access tokens (classic) from accessing your organizations". Para más información, consulta Aplicación de directivas de tokens de acceso personal en la empresa.

TareaPropietario de la organizaciónResponsable de la migración
Asignación del rol de migración para las migraciones de repositorioadmin:org
Ejecución de una migración de repositorios (organización de destino)repo, admin:org, workflowrepo, read:org, workflow
Descarga de un registro de migraciónrepo, admin:org, workflowrepo, read:org, workflow
Reclamación de maniquíesadmin:org

Personal access tokens for Azure DevOps

Your Azure DevOps personal access token must have work item (read), code (read), and identity (read) scopes.

If you want to use the --rewire-pipelines flag when generating a migration script, you will also need Build (Read) scope. To use the inventory-report and integrate-boards flags, you will need to grant full access to your personal access token.

If you want to migrate from multiple organizations, allow the personal access token to access all accessible organizations. For more information, see Use personal access tokens in Microsoft Docs.

Granting the migrator role

To allow someone other than an organization owner to run a 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 ADO2GH extension of the GitHub CLI or the GraphQL API.

Granting the migrator role with the ADO2GH extension

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

  1. On GitHub, 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.

  2. Establece personal access token como una variable de entorno, y reemplaza TOKEN en los comandos siguientes por el valor personal access token que has registrado antes.

    • Si usas Terminal, utiliza el comando export.

      Shell
      export GH_PAT="TOKEN"

    • Si usas PowerShell, utiliza el comando $env.

      Shell
      $env:GH_PAT="TOKEN"

  3. Use the gh ado2gh 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 ado2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE

    Nota:

    Si vas a conceder el rol de migración para GHE.com, también debes incluir la dirección URL de la API de destino para el subdominio de la empresa. Por ejemplo: --target-api-url https://api.octocorp.ghe.com.

Granting the migrator role with the GraphQL API

Puedes usar la mutación grantMigratorRole de GraphQL para asignar el rol de migración y la mutación revokeMigratorRole para revocarlo.

Debes usar una instancia de personal access token (PAT) que cumpla todos los requisitos de acceso. Para más información, consulta Ámbitos obligatorios para instancias de personal access token.

Mutación grantMigratorRole

Esta mutación de GraphQL establece el rol de migración.

mutation grantMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  grantMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}
Variable de consultaDescripción
organizationIdValor ownerId (o id. de organización) de la organización, de la consulta GetOrgInfo.
actorEquipo o nombre de usuario al que quieres asignar el rol de migración.
actor_typeEspecifica si el responsable de la migración es USER o TEAM.

Mutación revokeMigratorRole

Esta mutación elimina el rol de migración.

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

  1. Comprueba que tienes un rol suficiente para la tarea que quieres completar. Para más información, consulta Roles obligatorios.
  2. Crea una instancia de personal access token (classic) y asegúrate de conceder todos los ámbitos necesarios para la tarea que quieres completar. Solo puedes usar un personal access token (classic), no un fine-grained personal access token. Para más información, consulta Administración de tokens de acceso personal y Ámbitos obligatorios para personal access token.
  3. Si se aplica el inicio de sesión único de SAML para las organizaciones a las que necesitas acceder, autoriza la instancia de personal access token para el inicio de sesión único. Para más información, consulta Autorización de un token de acceso personal para su uso con el inicio de sesión único.

Configuring IP allow lists for migrations

Si el origen o el destino de la migración usa una lista de direcciones IP permitidas, ya sea la característica de lista de direcciones IP permitidas de GitHub, o bien las restricciones de lista de direcciones IP permitidas del proveedor de identidades (IdP), como Azure CAP, debe configurar las listas de direcciones IP permitidas en GitHub. Consulta Administrar las direcciones IP permitidas en tu organización y Restricción del tráfico de red a la empresa con una lista de direcciones IP permitidas.

  • Si usas la característica de lista de direcciones IP permitidas de GitHub, tendrás que agregar los intervalos IP de GitHub siguientes a la lista de permitidos para las organizaciones de origen o destino.
  • Si usa la lista de direcciones IP permitidas del IdP para restringir el acceso a la empresa en GitHub, debe deshabilitar estas restricciones en la configuración de la cuenta empresarial hasta que se complete la migración.

Los intervalos IP varían en función de si el destino de la migración es GitHub.com o GHE.com.

IP ranges for GitHub.com

Deberás agregar los siguientes intervalos IP a las listas de direcciones IP permitidas:

  • 192.30.252.0/22
  • 185.199.108.0/22
  • 140.82.112.0/20
  • 143.55.64.0/20
  • 135.234.59.224/28 (Nota: Introducido el 28 de julio de 2025)
  • 2a0a:a440::/29
  • 2606:50c0::/32
  • 20.99.172.64/28 (Nota: Introducido el 28 de julio de 2025)

Puedes obtener una lista actualizada de los intervalos IP usados por GitHub Enterprise Importer en cualquier momento con el punto de conexión "Obtener información meta de GitHub" de la API de REST.

La clave github_enterprise_importer de la respuesta contiene una lista de los intervalos IP usados para las migraciones.

Para más información, consulta Puntos de conexión de la API de REST para metadatos.

IP ranges for GHE.com

Debes permitir:

  • Rangos necesarios para todos los usuarios
  • Rangos adicionales que dependen de la región de residencia de datos

Para ver los rangos que se van a agregar, consulta Detalles de red para GHE.com.

Further reading