Overview of a migration from Azure DevOps to GitHub Enterprise Cloud

Overview

With GitHub Enterprise Importer, you can migrate to GitHub Enterprise Cloud on a repository-by-repository basis. For more information, see Acerca de GitHub Enterprise Importer.

If you're migrating from Azure DevOps (ADO), you can use this guide to plan and implement your migration and complete follow-up tasks.

Enterprises who migrate from ADO to GitHub typically follow a multi-phase approach.

1. Migrate repositories from ADO to GitHub.
2. Migrate pipelines from Azure Pipelines to GitHub Actions.
3. Migrate remaining assets, such as boards and artifacts, from ADO to GitHub.

This guide will guide you through completing the first phase, migrating repositories to GitHub, and assumes you're using the ADO2GH extension of the GitHub CLI.

Planning your migration

Para planear la migración, hazte las siguientes preguntas.

• How soon do we need to complete the migration?
• Do we understand what will be migrated?
• Who will run the migration?
• What organizational structure do we want in GitHub?

How soon do we need to complete the migration?

Determine your timeline, which will largely dictate your approach. The first step for determining your timeline is to get an inventory of what you need to migrate.

• Number of repositories
• Number of pull requests

Migrating from Azure DevOps, we recommend the inventory-report command in the ADO2GH extension of the GitHub CLI. The inventory-report command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. To install the ADO2GH extension of the GitHub CLI and authenticate, follow steps 1 to 3 in Migrating repositories from Azure DevOps to GitHub Enterprise Cloud.

Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing.

After you take inventory of the repositories you need to migrate, you can weigh your inventory data against your desired timeline. If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days. However, you may have various teams that are not able to migrate at the same time. In this case, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort.

1. Determine how many repositories and pull requests you need to migrate.
2. To understand when teams can be ready to migrate, interview stakeholders.
3. Fully review the rest of this guide, then decide on a migration timeline.

Do we understand what will be migrated?

Ensure that you and your stakeholders understand what data can be migrated by GitHub Enterprise Importer.

For migrations from ADO, GitHub Enterprise Importer only migrates Git repositories, including pull requests and some branch policies. Any other assets, such as pipelines, work items, artifacts, test plans, releases, and dashboards, will remain in ADO.

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO. For more information, see Configuring permissions.

Service hooks are not migrated from ADO, so you will need to recreate them separately.

1. Review the data that's migrated from Azure DevOps. For more information, see About migrations from Azure DevOps to GitHub Enterprise Cloud.
2. Make a list of any data that you'll need to manually migrate or recreate.

Who will run the migration?

To migrate a repository, you must be an organization owner for the destination organization, or an organization owner must grant you the migrator role.

1. Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else.
2. Si decides conceder el rol de migración, decide a qué persona o equipo vas a conceder el rol.
3. Concede el rol de migración a la persona o al equipo. For more information, see Managing access for a migration from Azure DevOps.
4. Confirma que la persona ha configurado correctamente personal access token para cumplir todos los requisitos de acceso. For more information, see Managing access for a migration from Azure DevOps.

What organizational structure do we want in GitHub?

Next, plan the organizational structure you'll create in GitHub. ADO and GitHub have different ways of organizing an enterprise's work.

• ADO: Organization > team project > repositories
• GitHub: Enterprise > organization > repositories

After migrating to GitHub, you should have only one enterprise account and a small number of organizations owned by that enterprise. Each organization from ADO should correspond to a single organization on GitHub. We do not recommend creating an organization on GitHub for each team project on ADO.

This may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams. For more information, see Acerca de los equipos de la organización.

If you want to break your migration effort into batches, the new structure can help you determine your batches. If you have more than one organization in ADO, and each organization's repositories are reasonably sized batches, consider batching by organization. You can use the GitHub CLI to generate a migration script for an entire organization on ADO.

1. Decide cuál será la nueva organización estructural.
2. Decida si necesitas dividir el esfuerzo de migración en lotes más pequeños.
3. Si es así, decide cómo quieres dividir las migraciones.

Running your migrations

Una vez que completes la planificación, puedes iniciar las migraciones reales. Para ayudar a descubrir problemas que podrían ser únicos para la empresa durante y después de la migración, se recomienda encarecidamente realizar ejecuciones de prueba de todas las migraciones. Después de resolver las incidencias detectadas por las ejecuciones de prueba, puedes ejecutar las migraciones de producción.

Las migraciones de prueba ayudan a determinar varios fragmentos críticos de información.

• Si la migración de un repositorio determinado se puede completar correctamente
• Si puedes devolver al repositorio a un estado en el que los usuarios puedan empezar a trabajar correctamente
• Cuánto tiempo tardará una migración en ejecutarse, lo que resulta útil para planear las programaciones de migración y establecer las expectativas de las partes interesadas

Las ejecuciones de prueba no necesitan mucha coordinación del tiempo. GitHub Enterprise Importer nunca necesita tiempo de inactividad para los usuarios de un repositorio que se va a migrar. Pero se recomienda detener el trabajo durante las migraciones de producción para asegurarse de que no se creen datos durante la migración, que después faltarían en el repositorio migrado. Esto no es un problema para las migraciones de prueba, por lo que las ejecuciones de prueba se pueden realizar en cualquier momento. A fin de reducir el tiempo necesario para completar las migraciones de prueba, puedes programar los lotes de las ejecuciones de prueba de manera consecutiva. Después, los usuarios de esos repositorios pueden validar los resultados por su cuenta.

We recommend creating a test organization to use as a destination for your trial migrations. Puedes usar una sola organización para todas las ejecuciones de prueba, o bien puedes crear una organización de prueba para cada organización de destino prevista. Considera la posibilidad de incluir -sandbox al final de los nombres de la organización, para aclarar que las organizaciones solo están pensadas para la validación de la migración y no para producción. Puedes eliminar las organizaciones de prueba cuando hayas terminado.

1. Create a test organization for your trial migrations.
2. Ejecuta las migraciones de prueba.
3. Completa las tareas de seguimiento que se describen a continuación para las migraciones de prueba.
4. Pide a los usuarios que validen los resultados de las migraciones.
5. Resuelve las incidencias detectadas por las migraciones de prueba.
6. Si el destino usa listas de direcciones IP permitidas, configura la lista para permitir el acceso por parte de GitHub Enterprise Importer. For more information, see Managing access for a migration from Azure DevOps.
7. Run your production migrations. For more information, see Migrating repositories from Azure DevOps to GitHub Enterprise Cloud.
8. Opcionalmente, elimina la organización de prueba.

Completing follow-up tasks

Después de que finalice cada migración, tendrás que completar algunas tareas adicionales antes de que el repositorio esté listo para funcionar.

• Checking the migration status
• Reviewing the migration log
• Setting repository visibility
• Configuring permissions
• Reclaiming mannequins
• Configuring IP allow lists

Checking the migration status

En primer lugar, compruebe si la migración se realizó correctamente o si fue errónea.

La forma de comprobar el estado de la migración depende de cómo ejecutó la migración.

• Si ejecutó la migración con GitHub CLI, de manera predeterminada, el proceso mostrará si la migración se realizó correctamente o si fue errónea una vez completada la migración. Si la migración fue errónea, se le indicará el motivo para la ejecución errónea.

  Migration completed (ID: RM_123)! State: SUCCEEDED
  

• Si ejecutó la migración con GitHub CLI con el argumento --queue-only opcional, el proceso se cerrará inmediatamente después de poner en cola la migración y no se le indicará si la migración se realizó correctamente o si fue errónea. Puede comprobar el estado de una migración mediante el comando wait-for-migration o revisando el registro de migración.

• Si ejecutó la migración mediante la API de GraphQL, puede consultar los campos state y failureReason en el objeto RepositoryMigration.

Si se la migración fue errónea, el registro de migración puede contener información adicional sobre la causa del error. Para más información, consulta Revisión del registro de migración.

Reviewing the migration log

En primer lugar, revise el registro de migración para cada repositorio migrado. Para más información, consulta Acceso a los registros de migración para GitHub Enterprise Importer.

Si se la migración fue errónea, el registro puede contener información adicional sobre la causa del error.

Si la migración se realizó correctamente, puede haber advertencias en el registro de migración que representan fragmentos específicos de datos (por ejemplo, solicitudes de cambios, problemas o comentarios) que no se migraron o se migraron con notas de precaución.

Para más información sobre cómo reconocer las advertencias de migración, consulta Solución de problemas de la migración con GitHub Enterprise Importer. Después de revisar las advertencias de migración, deberá tomar una decisión sobre si puede aceptar esas advertencias y avanzar.

Setting repository visibility

Todos los repositorios se migran como privados de manera predeterminada y solo el usuario que ha ejecutado la migración y los propietarios de la organización tendrán acceso al repositorio. Si no quieres que el repositorio sea privado, cambia la visibilidad.

• Puede establecer la visibilidad de un repositorio con la opción --target-repo-visibility de la CLI o la propiedad targetRepoVisibility de GraphQL.
• Puedes cambiar la visibilidad de un repositorio en el explorador. Para más información, consulta Configurar la visibilidad de un repositorio.
• Como alternativa, puedes usar GitHub CLI para cambiar la visibilidad del repositorio desde la línea de comandos. Incluso puedse agregar este comando al script que se ha generado para ejecutar las migraciones. Para más información, vea gh repo edit en la documentación de GitHub CLI.

Configuring permissions

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO.

If you used the ADO2GH CLI, GitHub Enterprise Importer will create two teams in GitHub for each team project in ADO. Each team is granted a different level of access to all repositories that originated from the team project.

Team	Access to migrated repositories
TEAM-PROJECT-Maintainers	Maintainer
TEAM-PROJECT-Admins	Admin

To give access to migrated repositories, you can add people to these teams. You can do this manually on GitHub, or if you chose to link the teams to Azure Active Directory (AAD) groups during your migration, by managing group membership in AAD. For more information about manually managing team membership, see Agregar miembros de la organización a un equipo.

If you aren't using the ADO2GH CLI, or if you require a permissions configuration that is more advanced than this default, configure permissions for your migrated repositories. You can modify the migration script to suit your needs, or you can manually configure permissions after your migration. For more information about managing access to repositories on GitHub, see Roles de repositorio para una organización.

1. Decide what permissions structure you require in GitHub.
2. If different than the default, make a plan for setting up team membership and permissions.

Reclaiming mannequins

Después de ejecutar una migración con GitHub Enterprise Importer, toda la actividad del usuario en el repositorio migrado (excepto las confirmaciones de Git) se atribuye a identidades de marcador de posición denominadas maniquíes.

Puedes reasignar el historial de cada maniquí a un miembro de la organización con la GitHub CLI o en el explorador. Si usas la datos GitHub CLI, puedes reclamar maniquíes de forma masiva. Para más información, consulta Reclamación de maniquíes para GitHub Enterprise Importer.

1. Decide si quieres reclamar maniquíes.
2. Planifica cuándo completarás las reclamaciones.
3. Reclama los maniquíes.
4. Si alguno de los miembros aún no tiene el acceso adecuado al repositorio por medio de la pertenencia al equipo, concede a los miembros acceso al repositorio. Para más información, consulta Administrar el acceso de una persona a un repositorio de una organización.

Configuring IP allow lists

If you added the IP ranges for GitHub Enterprise Importer to the IP allow list for your destination organization, you can remove those entries. Si has deshabilitado las restricciones de lista de direcciones IP permitidas del proveedor de identidades para la empresa de destino, ahora puedes volver a habilitarlas.

For more information, see Managing access for a migration from Azure DevOps.