Cómo migrar de GitHub a Codeberg: guía completa y actualizada para proyectos y webs

Cada vez son más los desarrolladores y equipos que se plantean dejar GitHub y mover sus repositorios a Codeberg, una opción libre, comunitaria y respetuosa con la privacidad. El motivo no es solo filosófico o ético, sino también práctico: Codeberg ofrece funciones modernas, servicios estables y la promesa de seguir siendo una alternativa no corporativa en un mundo cada vez más centralizado.

Si te has preguntado cómo migrar tus proyectos de GitHub a Codeberg o qué pasos deberías seguir para que la transición sea segura y completa, aquí vas a encontrar una guía detallada que integra toda la experiencia recopilada de quienes ya han dado el salto, además de recomendaciones útiles sobre herramientas, problemas habituales y consejos para no dejar flecos sueltos. Tanto si eres un particular con un pequeño proyecto como si gestionas repositorios colaborativos, este artículo te ayudará a entender el proceso, anticipar inconvenientes y aprovechar al máximo tu nuevo hogar en Codeberg.

¿Por qué migrar de GitHub a Codeberg?

Las razones que llevan a dejar GitHub son variadas, pero suelen combinar cuestiones técnicas, éticas y de futuro. Algunos motivos citados en experiencias recientes incluyen:

• Preocupaciones por el uso de código público en el entrenamiento de IA, especialmente a raíz de la incorporación de Copilot y otros sistemas que pueden infringir licencias o explotar tu trabajo sin reciprocidad.
• Baja transparencia sobre cómo se gestionan los flujos de trabajo y el código tras la compra por parte de Microsoft, así como la percepción de una prioridad corporativa que deja de lado a la comunidad open source.
• Deseo de participar en plataformas gestionadas por organizaciones sin ánimo de lucro, con compromisos claros hacia el software libre y la privacidad de los usuarios (Codeberg se gestiona desde Alemania y responde a la legalidad europea).
• Características técnicas avanzadas, como la posibilidad de federar repositorios con ForgeFed o aprovechar la familiaridad de la interfaz basada en Gitea/Forgejo.

Además, movimientos como “GiveUpGitHub”, promovidos por la Software Freedom Conservancy, animan a colectivos y proyectos a buscar alternativas más transparentes y éticas.

Preparativos antes de la migración

Antes de empezar la migración, dedica unos minutos a planificarlas cuentas y los recursos necesarios:

• Registra, si aún no la tienes, una cuenta en Codeberg. Asegúrate de completar el perfil y, si lo deseas, apoya económicamente a la plataforma.
• Asegúrate de tener acceso al repositorio de GitHub y permisos de propietario (especialmente relevante si vas a migrar metadatos como issues o wikis).
• Prepara tus claves públicas SSH, si quieres trabajar con autenticación robusta en Codeberg.
• Haz una revisión de issues abiertos, pull requests y ramas activas en GitHub. Puede que quieras cerrarlas, fusionarlas o dejarlo reflejado en comunicados para tus colaboradores.
• Considera el impacto sobre colaboradores frecuentes. Si tu proyecto tiene comunidad, debate los motivos y orienta el cambio con antelación para evitar malentendidos.

Creación de un token de acceso personal en GitHub

Para migrar datos sensibles (issues, wikis, releases, etiquetas, milestones, etc.) necesitas un token de acceso personal (PAT) en GitHub. El procedimiento actualizado (2024) es:

• Accede a GitHub. Haz clic en tu avatar (arriba a la derecha) y entra en Settings.
• Ve a Developer settings → Personal access tokens → Generate new token (elige Fine-grained tokens).
• Asigna un nombre descriptivo, elige el plazo de caducidad (por ejemplo, 7 días), y otorga el alcance adecuado (repo: ‘full control of private repositories’ si quieres migrar todo).
• Haz clic en Generate token. Copia la cadena que se muestra (solo la verás una vez) y guárdala en lugar seguro.

Migración automática desde Codeberg

Codeberg incorpora un asistente de migración que facilita copiar no solo el código, sino todo el contexto relevante del repositorio. La forma más habitual para iniciar el proceso es:

• Entra en tu cuenta de Codeberg y haz clic en el símbolo “+” (esquina superior derecha). Selecciona Nueva migración en el menú desplegable.
• Elige el servicio desde el que vas a importar (GitHub en este caso).
• Completa el formulario: Pega la URL del repositorio de GitHub y añade el token de acceso creado anteriormente.
• Marca las opciones de metadatos que quieras copiar (issues, wiki, etiquetas, releases, milestones…), además de elegir si el repositorio será público o privado en Codeberg.
• Ponle nombre al repo, descripción y selecciona el/la propietario/a.
• Pulsa Migrar Repositorio. El proceso puede tardar unos segundos o algunos minutos según tamaño y número de elementos a transferir.

Si algo va mal (fallos, tiempo de espera, mala conexión), puedes volver a intentarlo o crear un nuevo token en GitHub y repetir el procedimiento. Si ocurre un error y la migración deja un repositorio inaccesible en Codeberg, bórralo desde la sección ‘settings’ y repite desde el principio.

Migración manual o solo del código (sin metadatos)

En casos donde no necesitas importar issues o quieres un control más granular, puedes hacer una “clonación” manual tradicional:

1. Crea un nuevo repositorio en Codeberg (sin usar el asistente de migración).
2. Clona tu repositorio localmente desde GitHub:

 git clone https://github.com/tuusuario/turepo.git

3. Entra en el proyecto local y cambia el origen remoto a Codeberg:

 git remote set-url origin [email protected]:tuusuario/turepo.git

4. Pulsa git push –all origin y git push –tags origin para subir ramas y etiquetas.

Este método solo copia el código y el historial, pero no issues, wikis, releases, ni otros metadatos.

Herramientas de migración automática: scripts y soporte para múltiples repos

Si tienes decenas de repositorios o quieres migraciones por lotes, existen scripts que automatizan el proceso de GitHub a Codeberg. Uno de los más recientes se encuentra en GitHub – LionyxML/migrate-github-to-codeberg y te permite:

• Migrar todos o solo algunos repositorios, filtrando por propietarios o por nombres, y personalizando las descripciones.
• Ejecutar desde terminal en sistemas Linux y macOS, con dependencias mínimas (bash, curl, jq).
• Adaptarlo a tus necesidades específicas, ya que no migra elementos como wikis, PRs ni avatares de proyectos, pero sí todo el grueso del código y descripciones.
• Obtienes un registro del progreso y te permite consultar errores para revisarlos con facilidad.

Detalles a tener en cuenta tras la migración

Completar la migración en Codeberg no significa dejarlo todo listo. Hay detalles que pueden requerir actualizaciones manuales:

• Ajusta los remotos en los clones locales: cambia todas las rutas ‘origin’ en los proyectos locales al nuevo repositorio en Codeberg.
• Actualiza la documentación y los archivos README para reflejar la nueva ubicación del código, enlaces de issues o la nueva url del repo.
• Revisa los import paths si tienes código Go o algún lenguaje que utilice rutas ‘canónicas’ en los imports (puede que necesites actualizar líneas en go.mod u otras dependencias).
• Enlaza o notifica a tus colaboradores para que sepan que la actividad y seguimiento ahora se realiza en Codeberg. Puedes editar la descripción y URL en GitHub para apuntar a Codeberg y dejar un mensaje evidente en README.md indicando el cambio.
• Considera archivar el repositorio en GitHub una vez verifiques la migración, para evitar que nadie haga commits o cree issues accidentalmente en el origen.
• Toma nota de posibles cambios en los patrones de enlaces internos (por ejemplo, las urls de archivos y ramas pueden cambiar de ‘blob/main’ a ‘src/branch/main’).

¿Qué ocurre con los sistemas de integración continua (CI/CD)?

Uno de los principales retos tras abandonar GitHub es reconfigurar el CI/CD, ya que los GitHub Actions no funcionan fuera de su plataforma. Aquí tienes varias opciones:

• Woodpecker CI: Codeberg ofrece acceso a una instancia propia de Woodpecker, un sistema de integración continua que puedes solicitar y configurar para ejecutar tests, despliegues, etc. Eso sí, tendrás que pedir acceso mediante un issue, y esperar la aprobación para usar runners públicos. La documentación de Woodpecker te orienta para montar pipelines equivalentes a los de GitHub.
• Forgejo Actions: Codeberg está desplegando progresivamente Forgejo Actions (basadas en el estándar de GitHub Actions), pero no todas las funciones están disponibles y la compatibilidad no es total. Para workflows sencillos, basta con renombrar la carpeta ‘.github’ a ‘.forgejo’ y ajustar ciertas rutas de las acciones. En tareas voluntarias o personalizadas, puedes desplegar y vincular tu propio self-hosted runner.
• Otras integraciones: Si prefieres no usar la infraestructura de Codeberg, puedes configurar sistemas externos como GitLab CI, Jenkins, Travis o Cloud Build, aunque requerirá ajustes para acceder al código desde Codeberg.

Ojo con los indicadores de cobertura, publicación en PyPI y otros servicios que pudieran depender de la integración con GitHub. Muchos admiten configuraciones manuales (mediante API tokens y webhooks) si no existe soporte nativo con Codeberg.

Codeberg Pages y publicación de webs estáticas

Codeberg también permite alojar páginas web estáticas (al estilo GitHub Pages) mediante su opción Codeberg Pages. Los pasos básicos consisten en crear una rama específica (habitualmente ‘main’ o ‘gh-pages’), configurar el servicio y, si lo deseas, sincronizar la web con generadores como Jekyll, Hugo o Mkdocs.

El sistema de Codeberg Pages está en mantenimiento, pero sigue operativo y es una alternativa sencilla si no quieres salir de la plataforma. Si buscas una solución aún más potente para la documentación, Read the Docs está muy bien integrado con Python/Mkdocs y permite enlazar la generación automática de tu web mediante webhooks manuales desde Codeberg.

Migración de metadatos: issues, PRs y wikis

Uno de los valores diferenciales de la migración asistida de Codeberg es el soporte para importar issues, etiquetas, milestones, wikis y releases.

• Issues y pull requests: Puedes seleccionar cuáles migrar, aunque si tienes PRs antiguos, dependabot o entradas muy obsoletas, a veces conviene migrar solo los issues activos.
• Etiquetas, hitos y releases: La importación suele ser estable, copiando las descripciones y adjuntos. No obstante, revisa la estructura y adjuntos después, ya que a veces el proceso es más lento en los archivos grandes.
• Wikis: Si tu documentación principal está en el wiki, márcalo para migrar. Si tienes la documentación en archivos README o docs/, puedes obviarlo.
• Plantillas de issues y PRs: Forgejo y Codeberg soportan plantillas .md en el directorio raíz, pero para los PRs solo admiten un fichero principal, no carpetas tipo GitHub.

Revisión, limpieza y actualización de dependencias

Una vez completada la migración de tus proyectos, dedica tiempo a una revisión minuciosa:

• Edita los enlaces de dependencias en ficheros como pyproject.toml, go.mod, package.json, etc. para que apunten a las nuevas ubicaciones y evita advertencias o fallos futureos al instalar desde el nuevo origen.
• En plataformas como PyPI o Django Packages, actualiza los enlaces y realiza pequeños lanzamientos si es necesario, así tus usuarios y automatismos detectan a tiempo el cambio.
• Borra, desactiva o archiva funcionalidades redundantes en GitHub (issues, avisos, acciones) para evitar duplicidad de esfuerzos y facilitar una transición limpia.
• Notifica el cambio en tus redes, webs o canales de colaboración activa si el proyecto cuenta con comunidad externa.

Cuestiones especiales y consejos prácticos post-migración

Algunos aspectos adicionales que han comentado quienes han migrado recientemente incluyen:

• Si tienes proyectos en Go o estrategias de módulos con vanity domains, revisa con detalle las cabeceras y asegúrate de que los tags y versiones están sincronizados. Un fallo aquí puede causar la caché perpetua de rutas antiguas y dejar inservibles varias versiones.
• No olvides actualizar o reemplazar plantillas de CI/CD y archivos de configuración (por ej., .goreleaser.yaml, workflows, scripts de build, etc.).
• Si usas Docker o imágenes personalizadas, revisa los permisos y runners para las builds. Algunos servicios requieren ajustes en las variables de entorno y las rutas de acceso a Docker-in-Docker (DnD).
• La comunidad de Codeberg es receptiva y atenta. Si tienes problemas técnicos serios, es buena idea abrir un issue en el Community Tracker para que te ayuden con incidencias particulares.
• Si no necesitas portar toda la actividad, puedes mantener GitHub como espejo/archivo solo-lectura, dejando claro mediante notas y avisos que la evolución será a partir de ahora solo en Codeberg.

A la hora de terminar la migración, muchos desarrolladores han coincidido en la satisfacción de volver a tener control sobre sus repositorios, contribuir a la diversidad de plataformas libres y recuperar una sensación de comunidad, lejos del control corporativo centralizado. El proceso, aunque puede parecer extenso al principio, es asumible y ayuda a consolidar prácticas más libres, abiertas y sostenibles para el desarrollo de software.