Actualizar a Gitea 28: cinco breaking changes que debes corregir antes de reiniciar

Desarrollo
, , , , ,
1

Gitea 28.0.0, publicada el 30 de septiembre de 2026, trae cinco breaking changes que pueden romper una instalación existente en el primer arranque. Afectan a cinco áreas:

  • las reglas de salida (egress) para mirrors y migraciones;
  • el borrado de los runs de Actions a los 400 días;
  • Git 2.25 como versión mínima;
  • el registro de usuarios y el uso de DOMAIN;
  • una evaluación más estricta de los workflows.

Revisar cada uno lleva un minuto. Deshacerlos después de actualizar cuesta bastante más.

Nota de seguridad: esta versión incluye correcciones de seguridad. Al momento de publicar esta nota (1 de octubre de 2026), el equipo de Gitea aún no había publicado los detalles. Anunció que los añadirá al post de la versión en aproximadamente una semana. Es un motivo para actualizar pronto, pero después de hacer las comprobaciones de abajo.

¿Qué es Gitea y por qué se usa como alternativa a GitHub?

Gitea es una forja Git self-hosted con licencia MIT. Reúne repositorios, pull requests, issues, un registro de paquetes y su propio sistema de CI, Gitea Actions, en un solo binario o contenedor. Es la opción a la que recurren los equipos que quieren flujos de trabajo al estilo GitHub en su propia infraestructura. Si ya despliegas en tu propio servidor, encaja de forma natural con herramientas como Openship.

¿Por qué es la 28.0.0 y no la 1.28?

Gitea eliminó el prefijo histórico 1. de sus números de versión, así que la que habría sido la 1.28.0 es la 28.0.0. Sigue directamente a la serie 1.27.x y no hay nada más especial en la numeración. Aun así, revisa cualquier herramienta que interprete versiones 1.x o que tenga URLs de descarga fijadas. Más abajo explico qué cambió en las descargas.

¿Qué se rompe al actualizar a Gitea 28?

Estos son los cinco breaking changes que lista el equipo de Gitea, ordenados según la probabilidad de que te afecten.

1. ¿Tus mirrors y migraciones siguen llegando a los hosts que necesitan?

Ahora las migraciones, los mirrors y las demás operaciones de red de Git pasan por un proxy interno que aplica tus reglas de egress a las conexiones directas (#39426). En la mayoría de las instalaciones con el modo por defecto, lax, no cambia nada. Actúa antes de actualizar si alguno de estos casos aplica a tu instancia:

  • Usabas el preset external. Se eliminó. Si quieres una política de denegar por defecto, define EGRESS_MODE = strict y lista los hosts permitidos. [migrations] EGRESS_MODE cubre migraciones y mirrors, y [security] EGRESS_MODE cubre webhooks y OAuth2.
  • Usabas [security] ALLOWED_HOST_LIST como lista blanca exclusiva. En modo lax ya no restringe los hosts públicos. Define [security] EGRESS_MODE = strict para conservar el comportamiento anterior. Si la lista está definida sin un EGRESS_MODE explícito, Gitea registra un aviso al arrancar.
  • Tus listas de hosts usan comodines en IPs, un * suelto o example.*. Ninguno de esos formatos es válido ahora. Las entradas de dominio siguen la sintaxis de curl: example.com coincide con el dominio y sus subdominios, y *.example.com solo con los subdominios.
  • Tu [migrations] BLOCKED_HOST_LIST tiene alguna entrada inválida. Gitea se negará a arrancar.

En modo strict, las entradas sin puerto solo permiten el 80 y el 443. [migrations] ALLOWED_DOMAINS, BLOCKED_DOMAINS y ALLOW_LOCALNETWORKS quedan obsoletos en favor de ALLOWED_HOST_LIST y BLOCKED_HOST_LIST.

2. ¿Gitea va a borrar tus runs antiguos de Actions?

Sí, por defecto. Los runs de Actions completados con más de 400 días se borran ahora junto con sus jobs, logs y artifacts (#38855). Los elimina una nueva tarea cron, cleanup_action_runs, que por defecto se ejecuta a medianoche. Para conservarlo todo, define esto antes de actualizar:

[actions]
RUN_RETENTION_DAYS = 0

Ahora 0 significa “conservar para siempre” en RUN_RETENTION_DAYS, LOG_RETENTION_DAYS y ARTIFACT_RETENTION_DAYS. Los logs y artifacts siempre se borran junto con su run.

3. ¿Tu versión de Git es suficientemente nueva?

Gitea ya no arranca con una versión de Git anterior a la 2.25.0 (#39131). Si instalas Git por tu cuenta en lugar de usar el contenedor oficial, ejecuta git --version en el host antes de actualizar.

4. ¿Por qué dejó de funcionar el registro y por qué salen mal las URLs de clonado?

Hay dos cambios que llegan juntos en #39400:

  • El autorregistro está desactivado por defecto. Si tu instancia permite que la gente se registre, solo seguirá abierta si defines explícitamente [service] DISABLE_REGISTRATION = false.
  • [server] DOMAIN se ignora. El dominio de la instancia, incluido el dominio SSH por defecto, sale ahora de ROOT_URL. Si definiste DOMAIN pero nunca ROOT_URL, corrígelo primero. Si no, las URLs de clonado que copian tus usuarios pueden quedar mal.

5. ¿Tus workflows seguirán ejecutándose igual?

No necesariamente. Los workflows de Actions se evalúan de forma más estricta (#39358):

  • El if: a nivel de job se evalúa antes de expandir la matriz. Además, solo puede usar los contextos github, gitea, needs, vars e inputs. Mueve las condiciones sobre matrix a strategy.matrix.include/exclude o a un if: a nivel de step.
  • Ahora se aplica fail-fast en la matriz. Un job que falla puede cancelar el resto de las combinaciones. Define strategy.fail-fast: false si necesitas que terminen todas.
  • Los repositorios públicos ya no pueden llamar a reusable workflows de repositorios privados. Además, los workflows anidados ya no pueden superar los permisos del token de quien los llama.

¿Qué más debes revisar antes de reiniciar?

Hay tres cambios que no están en la lista oficial de breaking changes pero que también pueden pillarte:

  • Reverse proxy y WebSockets. Las notificaciones en vivo usan ahora un WebSocket en /-/ws, en lugar de server-sent events en /user/events. Tu proxy tiene que reenviar las cabeceras de upgrade de WebSocket. Si no lo hace, los contadores de notificaciones vuelven a funcionar por polling. Los despliegues con varios procesos de Gitea necesitan [websocket] PUBSUB_TYPE = redis. El ajuste [ui.notification] EVENT_SOURCE_UPDATE_TIME se eliminó.
  • Scripts de descarga. Los nombres de archivo ya no llevan el sufijo de versión del sistema operativo, por ejemplo gitea-28.0.0-windows-amd64.exe.
  • Builds eliminados. Los binarios ya no incluyen builds para x86 de 32 bits ni gogit, y el Snap ya no se compila para armhf. Las instalaciones en esas plataformas no tienen un artefacto oficial de la 28.0.0.

¿Cómo actualizar Gitea con Docker o desde el binario?

Gitea migra la base de datos automáticamente en el primer arranque, y no puedes ejecutar una versión anterior sobre una base de datos ya migrada. La documentación oficial recomienda hacer siempre un backup antes de una migración de base de datos:

  1. Detén la instancia de Gitea.
  2. Haz un backup de la base de datos, de la configuración de Gitea y de los datos en APP_DATA_PATH. Si usas almacenamiento externo, como S3 o MinIO, inclúyelo también. Un snapshot del volumen es una alternativa cómoda.
  3. Aplica los cambios de configuración de arriba.
  4. Reemplaza el binario, o haz docker pull de la nueva versión y vuelve a levantar el contenedor con docker o docker-compose.
  5. Arranca Gitea. El primer inicio tarda más mientras se ejecutan las migraciones.

La documentación también remite a contrib/upgrade.sh, en el código fuente de Gitea, que automatiza los pasos con binario en Linux. Antes de actualizar, resuelve los avisos de configuración obsoleta que aparecen arriba del panel de Administración del sitio, porque si no se resuelven, la siguiente versión puede negarse a arrancar. Si usas plantillas personalizadas, compruébalas también contra la nueva versión.

¿Gitea o Forgejo?

Forgejo es un fork de Gitea y, desde principios de 2024, un hard fork con código que diverge. Según el propio proyecto Forgejo, nació en octubre de 2022, después de que los dominios y la marca de Gitea pasaran a una empresa con fines de lucro. Hoy funciona bajo el paraguas de Codeberg e.V., una asociación sin fines de lucro. Se distribuye con licencia GPL v3+ desde su versión 9.0, mientras que Gitea sigue siendo MIT.

Para este artículo, la diferencia práctica es que Forgejo tiene su propia numeración y sus propias notas de versión. Nada de lo anterior aplica directamente a una instancia de Forgejo. Si estás evaluando pasar de Gitea a Forgejo, la guía de actualización de Forgejo documenta el proceso.

¿Qué ganas al actualizar a Gitea 28?

La versión es sustancial:

  • Audit log. Gitea registra los eventos relevantes para la seguridad, que se pueden filtrar y que los administradores pueden exportar en formato JSONL. Viene desactivado por defecto; actívalo con [audit] RECORD_OUTPUT = database. Los eventos se conservan 30 días salvo que cambies [audit] RETENTION_DAYS.
  • Cuentas bot. Son cuentas para automatización que solo se autentican con access tokens y no reciben notificaciones ni emails.
  • Suplantación de usuarios para administradores. Un administrador puede ver la instancia como un usuario concreto para reproducir problemas de acceso. Un banner marca la sesión, y con el audit log activo, los eventos registran ambas cuentas.
  • Deploy tokens HTTPS por repositorio. Son el equivalente HTTPS de las deploy keys SSH, con acceso de lectura o de lectura y escritura. Tanto los deploy tokens como los personal access tokens se pueden regenerar sin crear uno nuevo.
  • Aprobación de code owners en la protección de ramas. Bloquea el merge hasta que se aprueba cada regla de CODEOWNERS que coincide.
  • Configuración compartida de Redis. Un único [redis] CONN_STR sirve como valor por defecto para todos los subsistemas que usan Redis.

¿Qué hay de nuevo en Gitea Actions?

  • Una vista de la cola de builds, que muestra primero los jobs en ejecución y luego los que esperan, en el orden en que los toman los runners.
  • Vista previa de artifacts en el navegador: texto, imágenes, PDFs y HTML generado, como reportes de tests.
  • Matrices construidas a partir de los outputs de jobs anteriores.
  • strategy.max-parallel, para limitar cuántos jobs de la matriz corren a la vez.
  • Referencias self: a actions y workflows de la misma instancia.

Nada de esto compensa perder un año de historial de CI. Define RUN_RETENTION_DAYS, revisa ROOT_URL y repasa tus listas de hosts. Después, actualiza.