Cómo migrar de Gitea a Forgejo sin romper tus repositorios

Detienes Gitea, instalas Forgejo, copias app.ini y tu directorio de datos, e inicias el servicio tal como describe cada guía de migración. La UI web aparece. Entonces la migración de la base de datos falla, o peor aún, Forgejo se niega a arrancar porque tu versión de esquema es demasiado nueva para que la entienda. Estás en Gitea 1.23 o posterior, y la simple actualización in situ que todos documentan ya no se aplica a tu caso.

Forgejo se convirtió en un hard fork de Gitea a principios de 2024, y desde entonces los dos proyectos han divergido a nivel del esquema de base de datos. Cómo migras Gitea a Forgejo ahora depende por completo de tu versión de Gitea. Esta guía te da la ruta exacta para tu versión, los comandos completos tanto para instalaciones nativas como Docker, las soluciones alternativas para Gitea 1.23+ y una lista de verificación, para que migres sin perder repositorios, issues ni usuarios.

TL;DR

• El precipicio de versiones es real. Forgejo v10.0 fue la última versión en admitir una actualización directa transparente desde Gitea. Gitea v1.22 es la versión más alta que puede tomar la ruta directa compatible.
• En Gitea v1.22 o anterior: migra primero a Forgejo v10.0.x y luego actualiza Forgejo v10 a la versión actual (v15). Dos saltos, ambos compatibles.
• En Gitea v1.23 o posterior: no existe una ruta directa compatible de forma oficial. Eliges entre una degradación de SQL/esquema, scripts de migración de la comunidad, migración por repositorio/API, o una migración de puesta en escena con servidor nuevo usando uno de esos métodos. Cada una conlleva una contrapartida distinta de pérdida de datos.
• Haz una copia de seguridad de tu directorio de datos y tu base de datos antes de tocar nada. Cada ruta a continuación asume que tienes una copia de seguridad restaurable. Las rutas no compatibles lo asumen doblemente.
• Algunas cosas siempre necesitan atención después de la migración: prevé recrear o auditar los Personal Access Tokens, volver a registrar los runners de Actions, y eliminar y reconstruir el índice de búsqueda Bleve. Prevé esto sin importar la ruta que sigas.
• Migrar no es obligatorio. Gitea se mantiene activamente. La decisión de "quedarse en Gitea" se sostiene si el riesgo de migración supera el beneficio para tu situación.

Fuera del alcance de esta guía: migrar desde Gogs, GitHub o GitLab a Forgejo, y configurar Forgejo Actions desde cero.

Requisitos previos / Qué vas a necesitar

Antes de ejecutar un solo comando, confirma que tienes una copia de seguridad completa y restaurable de dos cosas: tu directorio de datos de Gitea (/var/lib/gitea en una instalación nativa por defecto) y tu base de datos. Si tu base de datos es SQLite, ese archivo vive dentro del directorio de datos; si es PostgreSQL o MySQL, vuélcala por separado con pg_dump o mysqldump. Una migración sin una copia de seguridad verificada no es una migración, es una apuesta.

También necesitarás:

• Tu versión actual de Gitea. Ejecuta gitea --version (o docker exec <container> gitea --version). Este número determina toda tu ruta.
• Tu tipo de base de datos: SQLite, PostgreSQL o MySQL. Algunas soluciones alternativas son específicas de cada base de datos.
• Acceso root o sudo en el servidor.
• Ser consciente de que la ruta compatible instala Forgejo v10.0 como salto intermedio. Forgejo v10.0 está en EOL desde el 16 de abril de 2025. Lo instalas solo durante la migración y lo actualizas de inmediato.

Por qué se rompió la ruta de actualización directa

En diciembre de 2024, el proyecto Forgejo publicó un declaración de compatibilidad que trazó una línea firme: "Las futuras versiones de Forgejo no admitirán actualizaciones desde instancias de Gitea que ejecuten la versión v1.23 o superior." Esa frase resume todo el problema en una sola línea.

Cuando Forgejo se bifurcó de Gitea a principios de 2024, las dos bases de código siguieron divergiendo, y los esquemas de base de datos se fueron separando. Forgejo mantuvo una ventana de compatibilidad para que los operadores existentes de Gitea pudieran migrar, pero esa ventana tuvo un final. Forgejo v10.0, publicada el 16 de enero de 2025, fue "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Cualquier versión más nueva que v10.0 no leerá directamente una base de datos de Gitea.

Lo que sorprende a la gente es el momento. Gitea v1.23 se lanzó a fines de 2024, y el la versión actual de Gitea en junio de 2026 es v1.26.4. Si mantuviste tu instancia de Gitea razonablemente actualizada, ya pasaste el salto y los tutoriales estándar ya no describen tu situación.

Conclusión de la sección: la ruta directa compatible llega hasta Gitea v1.22. Todo lo posterior necesita un paso adicional.

Encuentra tu ruta de migración según la versión de Gitea

Ejecuta gitea --version, busca tu fila y sigue la ruta de la tercera columna. Todo lo demás en esta guía es el detalle detrás de estas filas.

Las declaraciones de compatibilidad de versiones provienen directamente del anuncio oficial de compatibilidad de Forgejo: Gitea hasta v1.21 puede pasar a Forgejo v7.0 hasta v10.0, y Gitea v1.22 puede pasar a Forgejo v8.0 hasta v10.0. Ambas topan en v10.0 como el último destino directo compatible.

Bajo la cuestión de la versión hay tres estrategias de migración, y conviene verlas antes de los pasos detallados:

• En el mismo lugar, mismo servidor. Sustituye el binario o la imagen del contenedor en la máquina existente. Es el menor esfuerzo cuando tu versión lo permite; requiere el salto intermedio por v10.0.
• Preparación en un servidor nuevo. Aprovisiona un nuevo servidor y úsalo como destino seguro para el método de migración que corresponda a tu versión de Gitea. Esto protege el servidor original de Gitea y facilita la reversión, pero no evita el problema del esquema de base de datos de Gitea 1.23+.
• Migración por repositorio/API. Usa las herramientas de migración de Forgejo para traer los repositorios desde la instancia antigua de Gitea. El historial de Git es la parte fiable; la metadata como incidencias, PRs, etiquetas, lanzamientos, datos de wiki y comentarios debe tratarse como de mejor esfuerzo y verificarse repositorio por repositorio.

La ruta compatible: Gitea v1.22 o anterior

Si estás en Gitea v1.22 o anterior, el documentación oficial de migración describen una ruta de dos pasos: migrar a Forgejo v10.0.x y luego actualizar Forgejo v10 a la versión actual. El primer paso es una sustitución directa porque Forgejo v10.x lee una base de datos de Gitea v1.22; el segundo paso es una actualización normal de Forgejo.

Hay dos formas de hacer esto según cómo se ejecute Gitea en tu servidor. Elige la que coincida con tu configuración existente. Si Gitea se ejecuta como servicio del sistema, usa la ruta nativa. Si Gitea se ejecuta en un contenedor, usa la ruta de Docker. Forgejo v10.x actúa como reemplazo directo de Gitea v1.22.x.

Ruta nativa (systemd)

Haz una copia de seguridad primero. Luego instala Forgejo v10.0.x usando el paquete de tu distribución o el binario de release fijado a v10.0. Detén Gitea antes de copiar nada. Un servicio en ejecución que escribe en su directorio de datos durante la copia corromperá la copia.

# Stop the running Gitea service before touching its data
systemctl stop gitea

Copia la configuración y el directorio de datos a las ubicaciones de Forgejo, luego corrige la propiedad. El archivo de configuración debe ser legible por el grupo forgejo; los datos deben pertenecer al usuario forgejo.

# Copy the existing Gitea config to Forgejo's config path
cp /etc/gitea/app.ini /etc/forgejo/app.ini

# Back up the copied config before rewriting paths
cp /etc/forgejo/app.ini /etc/forgejo/app.ini.bak

# Update old Gitea data paths to Forgejo data paths
sed -i 's#/var/lib/gitea#/var/lib/forgejo#g' /etc/forgejo/app.ini

# Forgejo reads its config as the forgejo group; grant group write
chown root:forgejo /etc/forgejo/app.ini && chmod g+w /etc/forgejo/app.ini

# Copy the data directory and hand ownership to the forgejo user
rsync -aHAX --numeric-ids /var/lib/gitea/ /var/lib/forgejo/
chown -R forgejo:forgejo /var/lib/forgejo

Inicia Forgejo y habilítalo en el arranque.

# Start Forgejo and enable it at boot
systemctl start forgejo && systemctl enable forgejo

Antes de actualizar desde v10.0, vacía las colas para que no se pierda trabajo en curso durante el salto de versión.

# Flush pending queue items before the version upgrade
forgejo manager flush-queues

Ahora actualiza Forgejo v10.0.x a la versión actual reemplazando el binario con v15 y reiniciando el servicio, siguiendo el estándar Guía de actualización de Forgejo. Después de ambos saltos, ejecuta el doctor para revisar la base de datos y corregir lo que pueda.

# Check everything; write a log you can read if something is wrong
forgejo doctor check --all --log-file /tmp/doctor.log

Lee /tmp/doctor.log antes de aplicar cualquier corrección automática. Usa --fix solo cuando la salida del doctor identifica una reparación específica que entiendes, o cuando estás siguiendo una ruta oficial de solución de problemas.

Si doctor no reporta errores críticos y la interfaz web lista tus repositorios, la primera migración está completa.

Ruta Docker / contenedor

Si Gitea se ejecutaba como contenedor, ejecuta Forgejo de la misma manera. Usa la imagen de Forgejo v10.x como reemplazo directo de tu imagen de Gitea v1.22.x, apuntándola al mismo volumen de datos y base de datos. Primero confirma que tu versión de Docker sea al menos 20.10.6. Las versiones anteriores producen un comportamiento indefinido con los contenedores de Forgejo.

El detalle específico de los contenedores que suele confundir a la gente: las variables de entorno. Forgejo conserva el prefijo GITEA_ por compatibilidad, pero la documentación recomienda pasar ambos prefijos para que tu configuración sobreviva a una futura versión de Forgejo que elimine los nombres antiguos.

# docker-compose.yml (excerpt): pass both prefixes for forward compatibility
environment:
  - GITEA__database__DB_TYPE=postgres
  - FORGEJO__database__DB_TYPE=postgres
  # ...repeat the dual-prefix pattern for every config override you pass

Para contenedores rootless, los datos deben pertenecer al usuario 1000 y al grupo 1000, coincidiendo con el usuario de ejecución de la imagen rootless. Después de que el contenedor arranque en v10.x, ejecuta el mismo forgejo doctor check --all desde dentro del contenedor, luego actualiza la etiqueta de la imagen a la versión actual v15 y reinicia.

Si estás en Gitea v1.23 o posterior

Aquí es donde terminan las guías estándar y donde en realidad se encuentra la mayoría de las instalaciones actuales. No existe una ruta directa compatible de forma oficial desde Gitea v1.23+, así que cada opción a continuación proviene de la comunidad o implica pérdidas. Antes de ejecutar cualquiera de ellas, haz una copia de seguridad completa de tu directorio de datos y tu base de datos, y confirma que puedes restaurarla. Estos enfoques modifican datos de producción; la copia de seguridad es tu único deshacer.

Las tres opciones difieren en riesgo y en cuánto preservan. Elige aquella cuya contrapartida puedas aceptar.

Opción A: degradación del esquema SQL / parche de versión

La solución más acotada degrada la versión del esquema de la base de datos para que Forgejo v10 la trate como una base de datos v1.22.

Nota: no trates la actualización de versión como un downgrade completo por sí sola. La versión de migración registrada y el esquema real deben coincidir. En Gitea 1.23.x, prueba primero el downgrade completo en una copia y compara el esquema antes de apuntar Forgejo hacia ella.

Un mantenedor de Forgejo describió el SQL en Codeberg issue #7638:

-- Downgrade the recorded schema version to the v1.22 baseline (PostgreSQL/MySQL)
UPDATE version SET version=305 WHERE id=1;

Después de esto, sigues la ruta compatible como si estuvieras en v1.22. La advertencia crítica: el mantenedor confirmó esto solo para Gitea v1.23.1 específicamente, no para todo v1.23.x. El número de versión del esquema es exacto; aplicar el valor de destino equivocado a la versión de Gitea equivocada puede dejar la base de datos en un estado que ninguna migración puede recuperar. Esto es PostgreSQL/MySQL, no es compatible oficialmente y no está probado como procedimiento general.

Consejo práctico: fijar version=305 directamente omite la migración 304→305, que cambió la forma en que se codifican los secretos TOTP. Codeberg issue #8210 documenta que esto corrompe la autenticación de dos factores para los usuarios afectados. La solución es fijar la versión en 304 y dejar que la migración se ejecute, o borrar las filas de la tabla two_factor para que los usuarios se vuelvan a inscribir. No te saltes esto si alguna cuenta usa TOTP.

Opción B: scripts secuenciales de degradación SQL (Gitea 1.24-1.25.2)

Para versiones entre 1.24 y 1.25.2, un solo parche de versión no es suficiente: el esquema pasó por varios estados intermedios. Los scripts de la comunidad en xlrl/prepare-gitea-migration-to-forgejo hacen retroceder el esquema a través de las versiones intermedias hasta v1.22, después de lo cual sigues la ruta compatible. Estos scripts son trabajo de la comunidad, no un procedimiento autorizado, y apuntan a SQLite como caso principal. Ejecútalos solo contra una base de datos de la que ya tengas copia de seguridad.

Opción C: migración por API repositorio por repositorio (Gitea 1.26+ o cualquier versión)

La ruta de repositorio/API preserva los datos de Git de forma más fiable. Según el origen, los permisos y el método de migración, también puede estar disponible metadata opcional como incidencias, pull requests, etiquetas, hitos, lanzamientos, datos de wiki y comentarios, pero trátalos como algo de mejor esfuerzo y verifícalos repositorio por repositorio. Para un archivo que solo contiene código, esto suele ser suficiente; para un servidor donde el rastreador de incidencias es la memoria del equipo, prueba la transferencia de metadata antes de comprometerte con esta ruta.

Dos herramientas experimentales intentan migraciones más completas para 1.23+, pero tienen sus propias carencias. pacnpal/gitea2forgejo (GitHub) hace un volcado completo más sincronización por API y requiere una SECRET_KEY coincidente para transferir los campos cifrados, pero no traslada los Personal Access Tokens, los Actions runners, las URLs de callback de webhooks ni el 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) es una herramienta experimental basada en Podman que transfiere usuarios, claves, organizaciones, repos, issues, PRs, releases y mirrors, pero no los tokens de 2FA, los datos en tiempo de ejecución de Actions ni los manifiestos de paquetes OCI huérfanos. Trata ambas como experimentales y verifica el resultado con la matriz de transferencia de abajo.

Conclusión de la sección: no existe una ruta directa compatible de forma oficial desde Gitea 1.23+. Elige la opción cuya contrapartida de pérdida de datos puedas asumir, y haz una copia de seguridad antes de empezar.

Migrar en un servidor nuevo es más seguro, pero no evita el salto de versión

Un servidor nuevo es el lugar más seguro para preparar y verificar la migración, pero no es una ruta separada de compatibilidad de esquema. Si tu origen es Gitea v1.22 o anterior, instala primero Forgejo v10.0.x en el destino, restaura o copia allí los datos de Gitea, deja que Forgejo ejecute las migraciones de base de datos compatibles y luego actualiza esa instancia de Forgejo v10 a la versión actual de Forgejo.

Si tu origen es Gitea v1.23 o posterior, no restaures la base de datos de Gitea directamente en el Forgejo actual esperando que arranque. Aún necesitas uno de los enfoques no compatibles de 1.23+ mencionados arriba: un downgrade o reversión de SQL por etapas, una herramienta de migración de la comunidad, o una migración de repo/API. El servidor nuevo reduce el riesgo de rollback porque la máquina original de Gitea permanece intacta; no elimina la necesidad de manejar la discrepancia de versión de la base de datos.

Aquí es donde El Forgejo de un clic de Cloudzy app puede ayudar: úsala como instancia de destino limpia y luego ejecuta el método de migración que corresponda a tu versión de Gitea. La imagen del marketplace de Cloudzy te da un destino Forgejo listo en nuestro VPS de alto rendimiento, así que puedes concentrarte en los pasos de restauración, verificación y cambio en lugar de la instalación inicial. El plan de migración sigue dependiendo de si estás antes o después del salto de Gitea 1.22.

Qué se transfiere y qué debes rehacer

Parte de tus datos se traslada automáticamente, parte solo se traslada si se cumple una condición, y parte nunca se traslada y debe recrearse a mano. Saber qué es qué antes de empezar marca la diferencia entre un corte limpio y una semana de usuarios desconcertados.

Cuatro elementos golpean con más fuerza porque se rompen en silencio o afectan a todos los usuarios, así que trátalos con cuidado: los usuarios deben recrear o auditar sus Personal Access Tokens, debes volver a registrar tus Actions runners con el nuevo hostname, debes eliminar el índice de búsqueda Bleve para que Forgejo lo reconstruya limpiamente, y debes reescribir cualquier uses: las referencias cortas en tus flujos de trabajo de Actions a URL completas de GitHub, porque Forgejo y Gitea obtienen las acciones de espejos separados y una referencia relativa se resuelve en el lugar equivocado.

Consejo práctico: si ejecutas Gitea y Forgejo en paralelo durante la migración y ambos apuntan a la misma instancia de Redis, cambia Forgejo a Redis db=1 antes de empezar. Ambos usan db=0 por defecto, y si la comparten, Gitea consume los eventos de migración de Forgejo y destruye la cola de migración. (blog.mei-home.net documents this exact failure.)

Conclusión de la sección: los Personal Access Tokens, los runners de Actions, las claves de despliegue por repositorio y el índice de búsqueda Bleve siempre son manuales. Prográmalos como tareas de migración, no como algo que se piensa después.

Verifica que la migración se realizó con éxito

Empieza con el doctor, luego revisa los números y después prueba las cosas que los usuarios realmente hacen. El doctor detecta problemas a nivel de base de datos; las comprobaciones manuales detectan los problemas de pérdida de datos y acceso que el doctor no puede ver.

1. Ejecuta forgejo doctor check --all --log-file /tmp/doctor.log, luego lee el registro antes de hacer cambios. Usa --fix solo para una reparación específica que entiendas.
2. Confirma que el número de repositorios, los conteos de issues y PRs, y el número de objetos LFS junto con el tamaño total coinciden con tus cifras previas a la migración. Una discrepancia aquí significa que algo no se transfirió.
3. Prueba un push y un pull por SSH. Si a los clientes les aparece un desajuste de clave de host, no copiaste /etc/ssh/ssh_host_* al nuevo servidor.
4. Inicia sesión y confirma que el 2FA funciona para una cuenta que lo use. Si TOTP está roto, consulta la advertencia de la Opción A anterior.
5. Regenera los Personal Access Tokens, vuelve a registrar los runners de Actions y ejecuta un flujo de trabajo de prueba.

Algunos síntomas posteriores a la migración tienen causas conocidas. Un favicon o logo faltante significa que tus recursos de marca siguen en public/assets/img/ en lugar de custom/, donde Forgejo ahora los espera. Los errores 404 en las rutas de paquetes indican rutas de almacenamiento mal configuradas. Actions fallando con "repository not found" es el uses: problema de espejo. Cambia a URL completas. Una página en blanco o un error 500 tras iniciar sesión en una base de datos SQLite significa que estás por debajo del mínimo, que el documentación de actualización lo situó en Forgejo v1.19.3-0.

Cuándo tiene sentido quedarse en Gitea

Migrar es una elección, no una obligación. Si ya pasaste el salto y la complejidad de la migración supera el beneficio de gobernanza o funciones para tu situación, quedarte en Gitea es una elección legítima. Gitea se mantiene activamente (varias versiones al mes, actualmente en v1.26.4), y CommitGo ofrece opciones comerciales que incluyen Gitea Enterprise, Gitea Cloud y certificación SOC 2 Type 2 para los equipos que las necesitan.

También está la preocupación honesta del intermediario en EOL. La ruta directa compatible requiere instalar brevemente Forgejo v10.0, que está en EOL desde abril de 2025. Eso es aceptable como paso transitorio de migración del que te alejas de inmediato mediante una actualización, pero algunos operadores pondrán objeciones por motivos de política. Para ellos, la migración por repositorio/API a una instancia nueva de Forgejo puede evitar por completo el salto EOL, mientras que la puesta en escena con un servidor nuevo sigue dependiendo del método de migración que elijas.

Si tu razón para cambiar es la actividad de desarrollo, los datos respaldan a Forgejo como el proyecto más activo: un análisis de honeypot.net contó 3,039 commits de Forgejo frente a 1,228 commits de Gitea entre julio de 2024 y mayo de 2025, y 232 colaboradores de Forgejo frente a 153 de Gitea durante el año que terminó en mayo de 2025. Esa es una señal entre varias; sopésala frente al riesgo de tu migración en lugar de tratarla como decisiva.

Conclusión de la sección: migrar no es obligatorio. La decisión es una preferencia de gobernanza y actividad ponderada frente al riesgo de la migración, y ambas opciones son defendibles.

Elige tu camino y haz una copia de seguridad primero

Tu ruta de migración se reduce a un número: tu versión de Gitea. En v1.22 o anterior, sigues la ruta compatible de dos pasos a través de Forgejo v10. En v1.23 o posterior, eliges una solución alternativa según la pérdida de datos que puedas aceptar: degradación de SQL/esquema, scripts de la comunidad, migración por repositorio/API, o una migración de puesta en escena con servidor nuevo. Sea cual sea la ruta que tomes, haz primero una copia de seguridad de tu directorio de datos y tu base de datos, ejecuta forgejo doctor después, y confirma que tus recuentos de repositorios, incidencias y LFS coinciden con los que tenías al empezar.

Identifica tu versión, haz la copia de seguridad y sigue la fila correspondiente. La ruta es más compleja de lo que prometían los viejos tutoriales, pero está bien definida una vez que sabes dónde te encuentras respecto al salto de versión.

Preguntas frecuentes

¿Puedo actualizar directamente de Gitea a Forgejo?

Sí, si ejecutas Gitea v1.22 o anterior: actualiza directamente a Forgejo v10.0 y luego actualiza Forgejo v10 a la versión actual. No, si ejecutas Gitea v1.23 o posterior. Forgejo v10.0 fue la última versión que admitió una actualización directa transparente, así que las versiones más nuevas de Gitea necesitan una solución alternativa.

¿Qué versión de Gitea es compatible con Forgejo?

Gitea v1.22 y anteriores tienen una ruta de actualización directa compatible a Forgejo (hasta Forgejo v10.0, y luego hacia la versión actual). Gitea v1.23 y posteriores no tienen una ruta directa oficialmente compatible, porque Forgejo dejó de admitir actualizaciones transparentes desde Gitea v1.23+ a partir de las versiones posteriores a v10.0.

¿Puedo migrar de Gitea 1.26 a Forgejo?

Sí, pero no mediante una actualización directa compatible. Tus opciones son una migración por repositorio/API, donde el historial de Git es la parte fiable y la metadata debe probarse repositorio por repositorio, un script de migración experimental, o una migración de puesta en escena con un servidor nuevo usando uno de los métodos no compatibles 1.23+ mencionados antes. No existe una ruta in situ compatible de forma oficial desde Gitea 1.26.

¿Se transfieren mis Personal Access Tokens?

Prevé recrear o rotar los Personal Access Tokens después de la migración. Algunas rutas de migración no los conservan, y aun cuando los tokens siguen presentes, los usuarios deben auditar los alcances antes de volver a confiar en ellos. Cualquier script o integración que use tokens antiguos debe probarse y actualizarse después del corte.

¿Funcionan mis workflows de Gitea Actions en Forgejo?

En su mayoría, con dos correcciones necesarias. Workflow uses: las referencias cortas se rompen porque Forgejo y Gitea obtienen las acciones de espejos separados. Cámbialas a URL completas de GitHub (por ejemplo, uses: https://github.com/sammcj/dotenv-output-action@main). También debes volver a registrar tus Actions runners, porque sus tokens de registro están vinculados al hostname anterior.

¿Qué pasa con migrar de Gogs a Forgejo?

Esa es una migración distinta, con una ruta distinta, y queda fuera del alcance de esta guía. Esta guía cubre específicamente Gitea a Forgejo; para un origen en Gogs, consulta la documentación oficial de migración de Forgejo para el procedimiento específico de Gogs.