Solución de problemas de la migración con GitHub Enterprise Importer

Si se produce un error en la migración o se producen resultados inesperados, puedes probar los pasos comunes de solución de problemas.

En este artículo

Acerca de los pasos de solución de problemas de GitHub Enterprise Importer

Si se produce un error en la migración o genera resultados inesperados, prueba los primeros pasos de solución de problemas siguientes, que normalmente resuelven una variedad de incidencias. Si estos primeros pasos no resuelven la incidencia, comprueba si hay mensajes de error en los registros de la migración. Después, busca el mensaje de error en este artículo y prueba los pasos para la resolución.

Si no puedes resolver la incidencia después de probar los pasos de solución de problemas del mensaje de error, puedes ponerte en contacto con Soporte de GitHub.

Primeros pasos de solución de problemas

Antes de investigar más, prueba estos pasos de solución de problemas que suelen resolver una variedad de incidencias.

  1. Comprueba que usas la versión más reciente de la extensión de GitHub CLI que vas a utilizar para la migración. En caso contrario, actualiza a la versión más reciente.

  2. Comprueba que cumples todos los requisitos de acceso. Para obtener más información, consulte el artículo correspondiente para la ruta de migración.

  3. Intenta volver a ejecutar la migración. Algunas incidencias de migración son transitorias y un segundo intento puede funcionar.

  4. Prueba a ejecutar una migración en otro repositorio con datos similares. Esto ayudará a determinar si la incidencia es única para el repositorio o si representa un problema de forma de datos más amplio.

Si estos pasos no resuelven la incidencia, revisa los mensajes de error en los registros de migración. El registro que necesitas comprobar dependerá de si se ha producido un error en la migración o si se ha realizado correctamente.

Solución de problemas de migraciones con errores

Si se produce un error en la migración, revisa las entradas de registro detalladas generadas por la GitHub CLI para cada migración. El archivo de registro se guarda en el mismo directorio donde has ejecutado la migración.

El registro contiene un registro de cada comando que has emitido y todas las solicitudes de API que la GitHub CLI ha realizado en respuesta. Normalmente, los errores y los mensajes de error aparecen al final del registro.

No se pueden ejecutar migraciones

Si ves un error como No access to createMigrationMutation o Missing permissions, la cuenta personal no tiene el acceso necesario para ejecutar la migración. Asegúrate de que eres propietario de la organización o que se te ha concedido el rol de migración. Para más información sobre cómo conceder el rol de migración, consulta Acerca de GitHub Enterprise Importer.

Note

Si vas a migrar entre productos de GitHub, asegúrate de que eres propietario de la organización o que se te ha concedido el rol de responsable de la migración para las organizaciones de origen y destino.

El recurso está protegido por la aplicación de SAML de la organización

Este error indica que es necesario autorizar un personal access token al GitHub CLI para su uso con el inicio de sesión único de SAML. Para más información, consulta Autorizar un token de acceso personal para usar con un inicio de sesión único de SAML.

Respuesta 401 Unauthorized

Los errores que incluyen un código de estado 401 suelen indicar que la instancia de personal access token proporcionada a la GitHub CLI no tienen los ámbitos necesarios. Compruebe los ámbitos de las instancias de personal access token que ha proporcionado. Para obtener más información sobre los ámbitos necesarios, consulte el artículo correspondiente para la ruta de migración.

Respuesta 404 Not Found

Los errores que incluyen un código de estado 404 suelen indicar un error tipográfico en uno de los comandos. Revisa el registro de migración para ver el comando exacto que has escrito y comprueba si hay errores tipográficos en el repositorio de origen, la organización o el proyecto.

Respuesta Archive generation failed

Si recibes una respuesta Archive generation failed... al realizar la migración desde GitHub Enterprise Server, es probable que el repositorio sea demasiado grande. Para más información sobre los límites de tamaño de un repositorio, consulta Acerca de las migraciones entre productos de GitHub.

En primer lugar, intenta excluir versiones de la migración mediante la marca --skip-releases con el comando migrate-repo.

Si eso no funciona, se recomienda actualizar a GitHub Enterprise Server 3.8.0 o una versión posterior. Si no puedes realizar la actualización, otra opción consiste en generar manualmente los archivos del repositorio mediante ghe-migrator:

  1. Genera un archivo de migración para el repositorio. Solo debes exportar un repositorio a la vez. Para obtener instrucciones, consulta "Exportación de datos de migración desde la empresa".
  2. Carga el archivo de migración en el proveedor de almacenamiento de blobs que prefieras.
  3. Genere una dirección URL de corta duración para el archivo de migración que es accesible para GitHub, como una URL prefirmada de AWS S3 o una URL SAS de Azure Blob Storage.
  4. Llama al comando migrate-repo con las marcas --git-archive-url y --metadata-archive-url establecidas en la URL del archivo del paso anterior.

cipher name is not supported con error

Si vas a realizar la migración desde Bitbucket Server y se produce un error como cipher name aes256-ctr for openssh key file is not supported al ejecutarla, la clave privada SSH usa un cifrado no compatible. Para más información sobre los cifrados admitidos, consulta Administración del acceso para una migración desde Bitbucket Server.

Para generar una nueva clave SSH compatible, ejecuta el comando siguiente:

Shell
ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

Después de generar una nueva clave SSH, para poder usarla, debes agregar la clave pública a authorized_keys en la instancia de Bitbucket Server.

Subsystem 'sftp' could not be executed con error

Si vas a migrar desde Bitbucket Server y recibes un error como Subsystem 'sftp' could not be executed, SFTP no está habilitado en el servidor o la cuenta de usuario no tiene acceso SFTP.

Debes ponerte en contacto con el administrador del servidor y pedirle que habilite el acceso SFTP para tu cuenta de usuario.

Source export archive... does not exist con error

Si vas a migrar desde Bitbucket Server y recibes un error como Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist,GitHub CLI busca el archivo de migración en un lugar incorrecto en la instancia de Bitbucket Server.

Para resolver este problema, establece el argumento --bbs-shared-home para gh bbs2gh migrate-repo en el directorio principal compartido de Bitbucket Server o del Centro de datos. El directorio principal compartido predeterminado es /var/atlassian/application-data/bitbucket/shared, pero tu configuración puede ser diferente.

Puedes identificar el directorio principal compartido en Bitbucket Server.

  1. Desplázate al área Administración de la instancia de Bitbucket Server o del Centro de datos.
  2. En la barra lateral, en "Sistema", haz clic en Almacenamiento.
  3. En "Directorio compartido", consulta la ubicación del directorio principal compartido del servidor.

Si ejecutas Bitbucket Data Center en modo de clúster con varias notas, el directorio compartido se compartirá entre los nodos del clúster y se debe montar en la misma ubicación de cada nodo.

Repository rule violations found con error

Si recibes un error Repository rule violations found, como GH013: Repository rule violations found for refs/heads/main, los datos del repositorio de origen entran en conflicto con los conjuntos de reglas configurados en la organización de destino. Para más información, consulta Acerca de los conjuntos de reglas.

Puedes deshabilitar temporalmente los conjuntos de reglas durante la migración, o puedes usar el modo de omisión o la lista de omisión para excluir la migración de las reglas configuradas. Para más información, consulta Administración de conjuntos de reglas para repositorios de la organización.

Your push would publish a private email address con error

Si recibes un error Git source migration failed con GH007: Your push would publish a private email address, el origen de Git que estás intentando migrar incluye confirmaciones creadas por una dirección de correo electrónico que has bloqueado para que no se inserte en GitHub. Para obtener más información, consulta Bloquear las inserciones de la línea de comando que muestran tu dirección de correo electrónico personal en la documentación de GitHub Enterprise Cloud.

Para resolver este error, puedes volver a escribir el historial de Git para quitar la dirección de correo electrónico o deshabilitar la configuración "Bloquear inserciones de la línea de comandos que exponen mi correo electrónico".

Reconocimiento de advertencias del registro de migración

Incluso si la migración se realiza correctamente, debe revisar el registro de migración para comprobar si hay advertencias.

Advertencias en el punto de registro de migración a elementos específicos dentro del repositorio que no se pudieron migrar. Para más información, consulta Acceso a los registros de migración para GitHub Enterprise Importer.

Note

Si la propuesta "Migration Log" incluye "Migration completed" en la parte inferior, significa que el repositorio se ha migrado. Las advertencias solo indican que es posible que elementos específicos del repositorio, como un comentario en una solicitud de cambios, no se hayan migrado correctamente.

Advertencia: "Metadatos de repositorio demasiado grandes para la migración"

Si ves "Metadatos de repositorio demasiado grandes para la migración" en la incidencia "Registro de migración" o la GitHub CLI, el repositorio supera el tamaño máximo de archivo de 10 GB. Esto se suele deber a recursos de versión de gran tamaño. Intenta excluir las versiones de la migración con la marca --skip-releases del comando migrate-repo.

Advertencia: "Comentario no en diferencias"

Si vas a realizar la migración desde Azure DevOps, los comentarios de solicitudes de incorporación de cambios en las líneas que nunca se han cambiado en la solicitud de incorporación de cambios no se pueden migrar a GitHub. Verás esta advertencia para cada comentario que no se pueda migrar por este motivo.

Note

Esta limitación solo afecta a los comentarios de las líneas que no se han cambiado en una solicitud de cambios. Los comentarios de las líneas que se han cambiado en una solicitud de incorporación de cambios se migran.

Debes tener en cuenta que los comentarios afectados no estarán en el repositorio migrado, pero estas advertencias no necesitan ninguna otra acción por tu parte.

Advertencia: "Revisión de solicitud de cambios... no se pudo importar debido a un error REVIEW_THREAD_MISSING_END_COMMIT_OID"

Esta advertencia se produce cuando no se pudo migrar una revisión de la solicitud de cambios porque la confirmación a la que la revisión está adjunta ya no existe.

Esto suele ocurrir cuando se han quitado confirmaciones con un envío de cambios forzado o se ha eliminado una rama.

En este caso, los comentarios no se pierden, pero se migran como comentarios de solicitud de cambios insertados para conservar el historial, en lugar de como una revisión adjunta a una confirmación específica.

Las referencias de equipo se interrumpen después de una migración de la organización

Las referencias a equipos, como @octo-org/octo-team, no se actualizan como parte de una migración de la organización. Esto podría causar problemas en la organización de destino, como que los archivos CODEOWNERS no funcionen según lo previsto.

Puedes actualizar estas referencias después de la migración, o bien puedes conservar los nombres del equipo si cambias el nombre de la organización de origen para que puedas usar el nombre original de la organización de destino.

Por ejemplo, si la organización de origen es @octo-org y el archivo CODEOWNERS incluye una referencia al equipo @octo-org/octo-team, podrías cambiar el nombre de la organización de origen a @octo-org-temp antes de la migración, lo que te permite usar @octo-org como nombre de la nueva organización. Después, el equipo migrado se llamaría @octo-org/octo-team y el archivo CODEOWNERS del repositorio migrado funcionará según lo previsto.

Repositorios bloqueados

Después de una migración, es posible que encuentres que los repositorios de origen o de destino están bloqueados, deshabilitando el acceso al código del repositorio y a todos sus recursos, como incidencias y solicitudes de incorporación de cambios. Para más información sobre los repositorios bloqueados, consulta Acerca de los repositorios bloqueados.

El proceso para desbloquear un repositorio depende del producto GitHub donde se almacena el repositorio.

  • Si el repositorio bloqueado está en GitHub Enterprise Server, un administrador del sitio puede desbloquear el repositorio mediante el panel de administración del sitio. Para obtener más información, consulta Bloqueo de un repositorio.
  • Si el repositorio bloqueado está en GitHub.com, puedes ponerte en contacto con el administrador del sitio para desbloquear el repositorio.

Note

Si se ha producido un error en la migración, no todos los datos se han migrado. Si decides desbloquear y usar el repositorio, habrá pérdida de datos. Eliminar el repositorio bloqueado y volver a intentar la migración puede ser una mejor opción.

Contacto con Soporte de GitHub

Si sigues sin poder resolver la incidencia después de probar los pasos de solución de problemas anteriores, puedes ponerte en contacto con Soporte de GitHub mediante Portal de soporte de GitHub.