Migración de GitLab.com a GitLab autoalojado
Cuando un equipo se traslada de GitLab.com a su propia instancia, el código es solo una parte del trabajo. También hay que trasladar las incidencias (issues), las merge requests, las etiquetas, los hitos y su historial, preferiblemente sin copiar nada a mano.
GitLab dispone de un método integrado para ello, llamado direct transfer. Su instancia se conecta a GitLab.com por HTTPS con un token de acceso personal y copia un grupo junto con sus proyectos. La importación se ejecuta en segundo plano y, al terminar, puede comprobar cada elemento migrado.
Esta guía muestra la migración completa de un grupo: preparar GitLab.com, iniciar la importación, comprobar el resultado y completar los pasos que direct transfer no cubre. Todos los pasos se probaron en una migración real de GitLab.com a GitLab 19.5 en Ubuntu 26.04.
Qué necesita antes de la migración
Una instancia de GitLab autoalojada, instalada y en funcionamiento. Si aún no tiene una, instálela primero; consulte la guía Cómo instalar GitLab en un servidor dedicado.
Acceso de administrador a su instancia de GitLab.
El rol Owner en el grupo que desea migrar en GitLab.com. La página de importación solo muestra los grupos en los que usted es Owner.
Acceso HTTPS saliente desde su servidor a https://gitlab.com.
Suficiente espacio libre en disco en el servidor para todos los repositorios que migre y espacio libre en /tmp: GitLab descomprime allí los archivos temporales de la migración.
GitLab.com siempre ejecuta una versión más reciente que una instancia autoalojada. En nuestra prueba, esto no impidió la migración.
En toda esta guía, sustituya gitlab.example.com por el dominio de su instancia.
Qué se migra
Direct transfer traslada:
- el grupo y sus proyectos;
- los repositorios con todas las ramas y el historial de commits, los hashes de los commits se conservan;
- las incidencias y las merge requests con sus números originales;
- las etiquetas, los hitos y el historial de actividad;
- las fechas de creación originales.
Las contribuciones importadas y algunas pertenencias se vinculan primero a usuarios marcadores de posición (placeholder). Después de la importación, usted los reasigna a cuentas reales de su instancia.
Direct transfer no migra:
- las variables de CI/CD, las variables de las programaciones de pipelines y los triggers de pipelines;
- las deploy keys y los deploy tokens;
- las imágenes del container registry y el package registry;
- los registros y los artefactos de los jobs de CI/CD;
- los webhooks;
- los entornos y los feature flags;
- las reglas de aprobación de merge requests y las incidencias vinculadas;
- los mirrors remotos.
Los pipelines se migran como registros con su estado, pero sin registros de jobs ni artefactos.
Planifique cómo restaurará estos elementos antes de empezar. Las variables de CI/CD, las deploy keys y los deploy tokens suelen contener contraseñas y claves de API, por lo que debe recrearlas manualmente tras la importación. Las imágenes de contenedor y los paquetes no se copian: súbalos de nuevo a su instancia o reconstrúyalos con CI.
Preparar su cuenta de GitLab.com
Haga público su correo electrónico. En GitLab.com, seleccione su avatar en la esquina superior derecha y después Edit profile. En Public email, seleccione su dirección de correo y seleccione Update profile settings al final de la página.
Cree un token de acceso personal. Su instancia usa este token para leer sus datos en GitLab.com. En el menú izquierdo de su perfil, vaya a Access > Personal access tokens.
Seleccione Generate token y después Legacy token.
Rellene el formulario:
- Token name: cualquier nombre, por ejemplo
migration. - Expiration date: bastan unos días para la migración.
- Select scopes: seleccione
api. No lo confunda conread_api.
Seleccione Generate token. Copie el token, que empieza por glpat-, y guárdelo en un lugar seguro. GitLab.com lo muestra una sola vez.
No envíe el token por chats ni por correo. Quien lo tenga obtiene acceso completo a la API de su cuenta de GitLab.com hasta que el token caduque o se revoque.
Activar direct transfer en su instancia
Inicie sesión en su instancia de GitLab como administrador. Seleccione Admin en la esquina superior derecha, vaya a Settings > General y despliegue Import and export settings. En Allow migrating GitLab groups and projects by direct transfer, marque la casilla Enabled y seleccione Save changes.
En la misma sección, compruebe dos ajustes que afectan a la reasignación de usuarios tras la importación:
- Allow contribution mapping to administrators: si está activado, también puede reasignar contribuciones a cuentas de administrador;
- Skip confirmation when administrators reassign placeholder users: si está activado, las contribuciones se reasignan de inmediato, sin la aprobación del usuario.
Conectar su instancia con GitLab.com
Seleccione Create new (el icono del signo más) en la barra superior y después New group > Import group.
Rellene el formulario de conexión:
- GitLab source instance base URL:
https://gitlab.com - Personal access token: el token que creó en GitLab.com.
Seleccione Connect instance.
Se abre la página Import groups by direct transfer con la lista de sus grupos en GitLab.com.
Iniciar la importación
Busque el grupo en la lista. En Path of the new group, abra Select parent group y elija dónde colocar el grupo:
- No parent crea un grupo de nivel superior, igual que en GitLab.com;
- un grupo existente en su instancia importa el grupo en él como subgrupo. Si el grupo padre es privado, los grupos y proyectos públicos de GitLab.com pasan a ser privados tras la importación.
Esta elección es obligatoria. Hasta que seleccione un grupo padre, GitLab muestra Select a parent group y no inicia la importación.
Compruebe la ruta del nuevo grupo; de forma predeterminada coincide con el nombre en GitLab.com. Deje seleccionada Import user memberships para que se trasladen los miembros del grupo.
No modifique el grupo ni sus proyectos en GitLab.com una vez iniciada la importación. Los cambios realizados durante la migración pueden no llegar a su instancia. Pida al equipo que deje de subir código y de editar incidencias hasta que termine la importación.
Seleccione Import with projects en la fila del grupo. El estado cambia a Importing.
Si no aparece el botón Import with projects, compruebe Default minimum role required to create projects en Admin > Settings > General > Visibility and access controls. Si está en No one, GitLab no puede importar proyectos.
La importación se ejecuta en segundo plano, por lo que puede cerrar la página. El tiempo depende del número y el tamaño de los proyectos: en nuestra prueba, un grupo con dos proyectos pequeños tardó unos dos minutos.
Comprobar el resultado
Cuando la importación termina, el estado cambia a Complete.
Si el estado es Failed o Partially completed, seleccione Show errors para ver qué elementos no se importaron. Puede repetir una migración fallida o parcial desde la misma página o mediante la API.
Seleccione Migration details. La página Migration history muestra el grupo y cada proyecto con su propio estado.
Abra el grupo importado y compruebe su contenido.
Proyectos. Todos los proyectos del grupo deben aparecer en la lista.
Incidencias y merge requests. Abra Work items y Merge requests en el menú del grupo. Los números, las etiquetas y los hitos se conservan, y los elementos importados llevan la insignia Imported.
Repositorio. En un proyecto, vaya a Code > Branches. Compruebe que están todas las ramas esperadas y que sus últimos commits coinciden con el repositorio de origen.
Los autores de las incidencias y las merge requests aparecen como Placeholder users, por ejemplo Placeholder John Smith. Es lo esperado; los reasignará más adelante en esta guía.
Si una merge request muestra Cannot be merged automatically, ábrala y compruebe la pestaña Changes. Si no muestra cambios, la merge request tampoco tenía commits en GitLab.com, así que no hay nada que fusionar. No es un error de migración.
Recrear las variables de CI/CD
En GitLab.com, abra el proyecto y vaya a Settings > CI/CD, despliegue Variables y anote cada variable con sus opciones, por ejemplo Protected y Masked.
En su instancia, abra el mismo proyecto y la misma sección. La lista de variables del proyecto está vacía.
Seleccione Add variable y cree cada variable con la misma clave, el mismo valor y las mismas opciones. Repita el proceso con las variables de grupo, si las usa.
Las programaciones de pipelines se migran sin sus variables. Si sus programaciones usan variables, abra Build > Pipeline schedules en el proyecto y añádalas a cada programación.
Reasignar los usuarios marcadores de posición
Durante la importación, GitLab crea usuarios marcadores de posición para los autores de las contribuciones y para los miembros importados de GitLab.com. Para vincular sus incidencias, merge requests y comentarios a cuentas reales, reasigne los marcadores. Cree antes las cuentas de su equipo en la instancia, para tener a quién reasignar.
Abra el grupo de nivel superior, es decir, el propio grupo importado o su padre si lo importó como subgrupo, vaya a Manage > Members y seleccione la pestaña Placeholders. Necesita el rol Owner en este grupo. La lista Awaiting reassignment muestra todos los usuarios marcadores de posición.
En la fila de un marcador, abra Select user y elija la cuenta de su instancia. Compruebe que la cuenta correcta está seleccionada en la fila correcta y seleccione Reassign y Confirm reassignment.
La reasignación no se puede deshacer. Una elección incorrecta da las contribuciones y el acceso de una persona a otro usuario, así que revise cada fila antes de confirmar.
El estado cambia a Reassigning. Pasado un minuto, actualice la página: el marcador pasa a la pestaña Reassigned.
Ahora la incidencia muestra la cuenta real como autor y se conserva la fecha de creación original.
Si Skip confirmation when administrators reassign placeholder users está activado, como en nuestra instancia de prueba, las contribuciones se reasignan de inmediato. Si está desactivado, el usuario seleccionado debe aceptar primero la reasignación.
Las cuentas de servicio de GitLab.com, por ejemplo Duo Code Review, también llegan como marcadores. No tienen equivalente en su instancia: déjelas como están o seleccione Do not reassign. Para muchos usuarios, use Reassign with CSV file en la misma pestaña.
Finalizar la migración
Revoque el token. En GitLab.com, vaya a Access > Personal access tokens y seleccione Revoke junto al token de migración.
Actualice la dirección remota en los equipos de los desarrolladores. En cada copia local de un repositorio, apunte Git a su instancia:
git remote set-url origin [email protected]:group/project.git
Sustituya group/project por la ruta del proyecto en su instancia.
Configure de nuevo las integraciones y la automatización. Los webhooks, las deploy keys, los deploy tokens y los triggers de pipelines no se migran, así que recréelos en su instancia. Registre los runners de CI/CD en su instancia. Vuelva a conectar los servicios externos, como las notificaciones de chat o los gestores de incidencias, en los ajustes de cada proyecto.
Ejecute nuevos pipelines en las merge requests importadas. Los pipelines importados conservan su estado original y pueden cumplir Pipelines must succeed sin volver a ejecutarse. Antes de fusionar una merge request importada, ejecute un nuevo pipeline para ella en su instancia.
Cierre la copia antigua. Cuando todo funcione en su instancia, archive o elimine el grupo en GitLab.com para que nadie siga trabajando allí.
Para elegir un servidor para su instancia de GitLab, consulte la página Servidores dedicados para GitLab.
