Planeamiento de la migración a GitHub

Acerca de las migraciones

Si vas a cambiar entre productos de GitHub, por ejemplo, de GitHub Enterprise Server a GitHub Enterprise Cloud, o desde otra plataforma de Hosting de código, como Bitbucket Server o GitLab, a GitHub, querrás traer tu trabajo contigo: tu código, el historial del código y todas las conversaciones y colaboraciones anteriores.

Aquí se te guiará a través del planeamiento y la ejecución de una migración correcta. Aprenderás a prepararte para una migración, las herramientas que están disponibles para mover los datos y cómo hacer que el traslado sea correcto.

Terminología de la migración

Antes de usar esta guía para planear la migración, debes conocer estos importantes términos.

Término	Definición
Plataforma de hospedaje de código	La herramienta en línea que usas para hospedar los repositorios de código fuente y colaborar, como GitHub Enterprise Cloud, GitHub Enterprise Server, Bitbucket Server y GitLab.com.
Sistema de control de versiones (VCS)	La herramienta que usas para realizar un seguimiento de los cambios en el código fuente de la máquina donde realizas dichos cambios y administrarlos. Por ejemplo, si usas GitHub o GitLab como plataforma de hospedaje de código, usas el sistema de control de versiones de Git. Si usas Azure DevOps como plataforma de hospedaje de código, podrías usar Git o Control de versiones de Team Foundation (TFVC) como sistema de control de versiones subyacente. También es posible que no uses un VCS en absoluto.
Origen de la migración	Lugar desde el que migras. Normalmente, será una plataforma de hospedaje de código, pero puede ser tu propia máquina o una unidad de red compartida.
Destino de la migración	Producto de GitHub al que migras.
Ruta de migración	Combinación del origen y el destino de la migración, como "Bitbucket Server a GitHub Enterprise Cloud". En el caso de algunas rutas de acceso de migración, GitHub ofrece herramientas especializadas, como GitHub Enterprise Importer, para ayudarte a migrar.

Definir tu ámbito de migración

Antes de que puedas planear la migración, debes saber qué quieres migrar y cuándo.

Definición del origen y el destino

En primer lugar, determina desde dónde debes trasladar los datos. Suele ser, aunque no siempre, una plataforma de hospedaje de código.

La plataforma de hospedaje de código podría ser un producto de GitHub, como GitHub.com o GitHub Enterprise Server, o bien otra plataforma de hospedaje de código, como Bitbucket Server, GitLab o Azure DevOps. En función del tamaño y la complejidad de tu empresa, podrías usar varias plataformas de hospedaje de código diferentes.

Si no usas una plataforma de hospedaje de código en absoluto, es posible que almacenes el código en una unidad de red compartida, por ejemplo.

Dondequiera que resida el código, ese es el "origen de la migración".

También deberás saber a qué producto de GitHub migras o el "destino de la migración". Podría tratarse de GitHub.com, GHE.com, o GitHub Enterprise Server.

Creación de un inventario básico de los repositorios que deseas migrar

Una vez que hayas identificado el origen y el destino de la migración, establece los datos que necesitas migrar.

Debes crear un inventario de migración con una lista de todos los repositorios de los orígenes de migración que necesitas migrar. Se recomienda usar una hoja de cálculo. Como punto de partida, debes registrar los siguientes datos para cada repositorio:

• Nombre
• Propietario: en GitHub, este sería una organización, pero en otras herramientas, podría haber un tipo de propietario diferente
• URL
• Última marca de tiempo actualizada
• Número de PR (o el equivalente en el origen de la migración)
• Número de incidencias (o el equivalente en el origen de la migración)

Si migras desde GitHub Enterprise Cloud o GitHub Enterprise Server, puedes obtener estos datos con la extensión gh-repo-stats para la GitHub CLI. Con unos pocos comandos, gh-repo-stats se conectará con la API del origen de la migración y creará un archivo CSV con todos los campos recomendados. Para obtener más información, consulta el repositorio mona-actions/gh-repo-stats.

Si va a migrar desde Azure DevOps, se recomienda el comando inventory-report en ADO2GH extension of the GitHub CLI. El comando inventory-report se conectará con la API de Azure DevOps y, a continuación, creará un archivo CSV muy sencillo con algunos de los campos sugeridos anteriormente. Para obtener más información sobre la instalación de ADO2GH extension of the GitHub CLI, consulta "Migración de repositorios desde Azure DevOps a GitHub Enterprise Cloud".

Si vas a migrar desde Bitbucket Server o Bitbucket Data Center, se recomienda el comando inventory-report en BBS2GH extension of the GitHub CLI. El comando inventory-report usará la API de la instancia de Bitbucket para compilar un ARCHIVO CSV sencillo. Para obtener más información sobre la instalación de BBS2GH extension of the GitHub CLI, consulta "Migración de repositorios desde Bitbucket Server a GitHub Enterprise Cloud".

Para otros orígenes de la migración, crea tú mismo el inventario de migración. Podrías crear la hoja de cálculo mediante las herramientas de informes del origen, si están disponibles, o la API, o podría crear el inventario manualmente.

Sea cual sea el enfoque que elijas para el inventario de migración, toma nota del proceso que has seguido o los comandos que has ejecutado. Es muy probable que quieras volver a ejecutar el inventario a medida que continúes planeando la migración.

Una vez que tengas una lista de todos los repositorios, podrás decidir cuáles quieres migrar. Una opción es migrar absolutamente todo. Sin embargo, una migración es una gran oportunidad para evaluar los repositorios y quitar los que ya no son necesarios. Hemos detectado que muchas empresas tienen cientos o incluso miles de repositorios innecesarios y sin usar, y archivarlos puede hacer que la migración resulte mucho más sencilla.

Medición de los tamaños de los repositorios

Una vez completado el inventario de migración básico, recopila información sobre el tamaño de los repositorios. Si los repositorios son grandes o contienen archivos individuales de más de 100 MB, esto puede hacer que la migración sea más larga y arriesgada y limitar las herramientas de migración que están a tu disposición.

Si usas Git como sistema de control de versiones, no solo importan los archivos grandes que hay actualmente en el repositorio, sino también los archivos grandes del historial del repositorio. Por ejemplo, si tenías un archivo de más de 100 MB en el repositorio en el pasado, ese archivo seguirá estando presente en el historial de Git, a menos que hayas reescrito el historial para quitar todos los seguimientos del archivo. Para obtener más información sobre cómo reescribir el historial, consulta "Acerca de los archivos grandes en GitHub".

Si has usado gh-repo-stats para crear el inventario, ya tendrás algo de información básica sobre el tamaño de los repositorios. Para crear un inventario de migración completo, deberás obtener detalles más completos sobre los datos dentro de los repositorios.

A continuación, sigue estas instrucciones para agregar los siguientes datos al inventario de migración para cada repositorio:

• Tamaño del archivo más grande (también conocido como "blob")
• Tamaño total de todos los archivos ("blobs")

Si usas un sistema de control de versiones distinto de Git o no se realiza un seguimiento de los archivos con un sistema de control de versiones, traslada primero los repositorios a Git. Para obtener más información, vea «Agregar código hospedado localmente a GitHub».

A continuación, usa la herramienta de código abierto, git-sizer, para obtener estos datos para el repositorio.

Requisitos previos

1. Instalar git-sizer. Para más información, consulta el repositorio github/git-sizer.
2. Para comprobar que git-sizer está instalado, ejecuta git-sizer –version. Si ves un resultado similar a git-sizer release 1.5.0, la instalación se realizó correctamente.
3. Instalar jq. Para obtener más información, consulta Descarga de jq en la documentación de jq.
4. Para comprobar que jq está instalado, ejecuta jq –-version. Si ves un resultado similar a jq-1.6, la instalación se realizó correctamente.

Medición del tamaño del repositorio con git-sizer

1. Para clonar el repositorio desde el origen de la migración, ejecuta git clone --mirror.
2. Ve al directorio donde has clonado el repositorio.
3. Para obtener el tamaño del archivo más grande del repositorio en bytes, ejecuta git-sizer --no-progress -j | jq ".max_blob_size".
4. Para obtener el tamaño total de todos los archivos del repositorio en bytes, ejecuta git-sizer --no-progress -j | jq ".unique_blob_size".
5. Agrega los valores de los pasos anteriores al inventario.

Acerca de los tipos de migración

Hay tres enfoques que puedes adoptar al ejecutar una migración, que proporcionan diferentes niveles de fidelidad de la migración.

Tipo de migración	Definición	Requisitos
Instantánea de origen	Migra el estado actual del código, tal como está actualmente, pero no incluyas ninguno del historial de revisiones.	Posible para cada origen y destino, incluso si no se realiza un seguimiento del código actualmente en un sistema de control de versiones (VCS).
Origen e historial	Migra el estado actual del código y su historial de revisiones.	Posible si has estado realizando un seguimiento de tus cambios en Git o un sistema de control de versiones que se puede convertir en Git antes de la migración.
Origen, historial y metadatos	Migra el estado actual del código y su historial de revisiones, además del historial de colaboración, como incidencias y PR, y la configuración.	Requiere herramientas especializadas, que no están disponibles para todas las rutas de acceso de migración.

Al decidir qué tipo de migración se va a completar, ten en cuenta las necesidades de tu organización y las herramientas que están disponibles.

Es posible que desees usar diferentes estrategias para distintos repositorios. Por ejemplo, puedes tener algunos repositorios antiguos y archivados donde el historial no es importante, mientras que una migración de alta fidelidad es fundamental para el código más activo.

Acerca de nuestros diferentes modelos de soporte técnico para la migración

Puedes optar por completar una "migración de autoservicio", donde planees y ejecutes tu propia migración solo con nuestra documentación, sin ningún soporte técnico profesional de GitHub.

Como alternativa, es posible que prefieras trabajar con el equipo de Expert Services de GitHub o un asociado de GitHub, al que llamamos "migración dirigida por expertos". Con una migración dirigida por expertos, te beneficias del conocimiento y la experiencia de un experto que ha ejecutado previamente decenas o incluso cientos de migraciones, y obtienes acceso a herramientas de migración adicionales que no están disponibles para autoservicio.

Si vas a migrar una gran cantidad de datos, es probable que te beneficies de una migración dirigida por expertos. Por ejemplo, si vas a migrar miles de repositorios o tienes repositorios complejos con un tamaño superior a 5 GB aproximadamente, recomendamos contactar con Expert Services.

Para obtener más información sobre las migraciones dirigidas por expertos, ponte en contacto con el representante de la cuenta o Expert Services.

Decisión sobre qué herramientas se van a usar

Para planear la migración, ten en cuenta el destino y el origen. Estas consideraciones determinan la ruta de acceso de la migración. Para obtener más información, consulte "Rutas de migración a GitHub."

Diseño de la estructura de la organización para el destino de la migración

En GitHub, cada repositorio pertenece a una organización. Las organizaciones son cuentas compartidas en las que las empresas y los proyectos de código abierto pueden colaborar en muchos proyectos a la vez, con características sofisticadas de seguridad y administrativas. Para más información, consulta "Acerca de las organizaciones".

Tanto si vas a adoptar GitHub por primera vez como si ya usas GitHub, haz una pausa para considerar la estructura más eficaz para las organizaciones y los repositorios después de la migración. El diseño que elijas puede maximizar la colaboración y detección y minimizar la carga administrativa, o puede crear silos innecesarios y una sobrecarga administrativa.

Se recomienda minimizar el número de organizaciones y estructurarlas según uno de los cinco arquetipos. Para obtener instrucciones detalladas, consulta "Procedimientos recomendados para estructurar organizaciones en tu empresa".

Realización de una migración de simulacro para cada repositorio

Antes de continuar con el planeamiento, realiza una migración de simulacro, incluidos todos los repositorios. Los simulacros completos te permitirán lo siguiente:

• Comprobar que la herramienta que has elegido funciona para los repositorios
• Confirmar que la herramienta cumple tus requisitos
• Conocer con exactitud qué datos se migran y cuáles no
• Saber cuánto tardará la migración para poder programar la migración de producción

No hay nada singular en una migración de simulacro. Solo tienes que ejecutar una migración normal y, a continuación, eliminar el repositorio en el destino de la migración.

Planeamiento de los pasos previos a la migración y posteriores a la misma

La migración de los repositorios constituye solo un paso de un proceso de migración más grande. Habrá otros pasos que debas seguir y, posiblemente, datos o valores de configuración que tendrás que migrar manualmente.

La lista completa de pasos necesarios para la migración dependerá de tus circunstancias particulares, pero hay algunos pasos previos a la migración que se aplican a todas las migraciones:

• Informar a los usuarios con antelación sobre la migración futura y su escala de tiempo
• Enviar recordatorios poco antes de que se realice la migración
• Configurar cuentas de usuario en GitHub para el equipo
• Enviar instrucciones a los usuarios para actualizar sus repositorios locales de modo que apunten al nuevo sistema

También hay pasos posteriores a la migración que se aplican a todas las migraciones:

• Informar a los usuarios de que la migración ha finalizado
• Vincular la actividad a los usuarios en el destino de la migración
• Retirar el origen de la migración

Estos son otros pasos que debes tener en cuenta al planear la migración.

Migración de la integración continua (CI) y la entrega continua (CD)

Si te mueves entre productos de GitHub, usas ya GitHub Actions para CI/CD y vas a seguir utilizando GitHub Actions, no hay mucho que hacer. Los archivos de flujo de trabajo de los repositorios se migrarán automáticamente. Si usas ejecutores autohospedados, deberás configurarlos en tu nueva organización de GitHub de modo que estén listos para ejecutar los flujos de trabajo.

Si no usas GitHub Actions, la situación es más complicada. Si tienes previsto seguir usando el mismo proveedor de CI/CD, deberás comprobar que el proveedor es compatible con GitHub y conectar el proveedor a tu nueva organización y repositorios.

Si tienes pensado cambiar a GitHub Actions, no se recomienda hacerlo al mismo tiempo que se migran los repositorios. En su lugar, espera hasta una fecha posterior y realiza la migración de CI/CD como paso independiente. Esto hace que el proceso de migración sea más fácil de administrar. Cuando estés listo para migrar, consulta "Migrar a GitHub Actions".

Migración de integraciones

Es probable que uses integraciones con el proveedor de hospedaje de código, ya sean desarrolladas internamente o proporcionadas por otros proveedores.

Si ya usas GitHub, tendrás que volver a configurar las integraciones para que apunten a las nuevas organizaciones y repositorios. Si un proveedor proporciona la integración, ponte en contacto con él para obtener instrucciones. Si la integración se desarrolló internamente, vuelve a configurar la integración en la nueva organización; para ello, genera nuevos tokens y claves.

Si no estás familiarizado con GitHub, comprueba si las integraciones son compatibles con GitHub y, a continuación, vuelve a configurarlas. Si usas integraciones desarrolladas internamente, vuelve a escribirlas para trabajar con la API de GitHub. Para obtener más información, vea «Documentación de API REST para GitHub».

Vinculación de la actividad a los usuarios en el destino de la migración

Si migras el historial de colaboración o los metadatos, así como código, deberás vincular la actividad de los usuarios a sus nuevas identidades en el destino de la migración.

Por ejemplo, supongamos que @octocat ha creado una incidencia en tu instancia de GitHub Enterprise Server y migras a GitHub Enterprise Cloud. En GitHub Enterprise Cloud, @octocat podría tener un nombre de usuario completamente diferente. El proceso de atribución permite vincular la actividad de los usuarios con estas nuevas identidades.

La manera en que funciona la atribución varía según la herramienta:

• Si usas ghe-migrator, gl-exporter o bbs-exporter, decidirás cómo deseas atribuir los datos con antelación e incluirás un archivo de asignación al importar los datos.
• Si usas GitHub Enterprise Importer, los datos se vincularán a identidades de marcador de posición denominadas "maniquíes" y puedes asignar este historial a usuarios reales después de migrar los datos. Para obtener más información, vea «Reclamación de maniquíes para GitHub Enterprise Importer».

Administración de equipos y permisos

La mayoría de los clientes usan equipos para administrar el acceso a los repositorios. Con los equipos, en lugar de conceder a Mona acceso directo a un repositorio, puedes agregarla al equipo de ingeniería y proporcionar a todo este equipo acceso al repositorio. Para obtener más información, vea «Acerca de los equipos».

Puedes crear los equipos y agregar miembros del equipo antes de migrar los repositorios. Es posible que quieras administrar los miembros a través de tu proveedor de identidades (IdP) vinculando los equipos a grupos de IdP. Para obtener más información, vea «Sincronizar un equipo con un grupo de proveedor de identidad».

Sin embargo, no puedes asociar los equipos a los repositorios hasta que los hayas migrado.