Forgejo v17.0 introduce cambios disruptivos en webhooks y nuevas herramientas de colaboración

El proyecto Forgejo lanzó la versión 17.0 el 15 de octubre de 2026, marcando una actualización importante para los administradores de forjas Git autoalojadas. Esta versión principal introduce varios cambios disruptivos, que afectan especialmente a cómo los webhooks gestionan los eventos de acciones, junto con nuevas funciones para la gestión de equipos y la colaboración en código. Se recomienda encarecidamente a los usuarios realizar copias de seguridad de sus instancias y revisar las guías de migración antes de actualizar.

Qué ha ocurrido

Forgejo v17.0 sustituye los anteriores eventos de webhook "action run" por eventos "workflow run" más capaces. Este cambio es necesario porque la estructura de eventos anterior era limitada y problemática para pipelines complejos de CI/CD. Los nuevos eventos de workflow run proporcionan datos más ricos y una mejor alineación con los estándares modernos de automatización. Sin embargo, esta transición no es automática. Los webhooks existentes configurados para escuchar ejecuciones de acciones dejarán de funcionar si no se actualizan, ya que cabeceras como X-*-Event y la clave action han cambiado significativamente. Las notificaciones de finalización también se emiten ahora solo después de que todos los trabajos de una ejecución hayan terminado, lo que altera el momento de las alertas.

Además de los webhooks, la versión ajusta cómo se renderizan los enlaces absolutos en los documentos. Los enlaces a recursos dentro de un repositorio ahora se resuelven en relación con la raíz del repositorio en lugar de la raíz de la instancia. Este cambio mejora la compatibilidad con otras forjas Git, facilitando futuras migraciones. Los enlaces absolutos en descripciones de issues y comentarios siguen resolviéndose contra la raíz de la instancia para preservar el comportamiento existente en esos contextos. Estos ajustes buscan estandarizar el comportamiento de Forgejo con las expectativas del ecosistema más amplio manteniendo la estabilidad para el contenido visible al usuario.

Detalles clave

• Migración de Webhooks Requerida: Los eventos de webhook de ejecución de acciones están obsoletos y son reemplazados por eventos de ejecución de workflows; se requiere una migración manual debido a los cambios en cabeceras y payloads.
• Actualización de Resolución de Enlaces: Los enlaces absolutos en documentos renderizados ahora se resuelven en relación con la raíz del repositorio, mejorando la compatibilidad entre forjas.
• Invitaciones a Organizaciones: Los administradores pueden habilitar la membresía basada en invitaciones mediante app.ini, permitiendo a los usuarios aceptar o rechazar invitaciones a organizaciones enviadas por correo electrónico.
• Soporte para FUNDING.yml: Los repositorios y perfiles con un archivo FUNDING.yml ahora muestran un botón "Donar" en la interfaz web.
• Mejoras en LFS: El soporte para Git Large File Storage incluye mejor navegación, manejo de punteros y vistas para descubrir commits que referencian archivos LFS específicos.
• Cronograma de Soporte: La versión 17.0 es un lanzamiento no-LTS soportado hasta el 28 de enero de 2027, siguiendo el ciclo de lanzamientos principales trimestral del proyecto.

Contexto

Los webhooks son mensajes automatizados enviados de una aplicación a otra cuando ocurre un evento específico. En forjas Git como Forgejo, los webhooks a menudo activan pipelines de CI/CD, notificaciones de chat o scripts de despliegue. Cuando cambia la estructura de estos mensajes, como se ve en la transición de eventos de ejecución de acciones a eventos de ejecución de workflows, los sistemas receptores pueden fallar al analizar los datos correctamente. Por eso, la inspección y prueba manuales son críticas durante las actualizaciones importantes. De manera similar, la resolución de enlaces determina cómo se interpretan las URLs dentro de los archivos markdown. Cambiar de la resolución desde la raíz de la instancia a la raíz del repositorio asegura que los enlaces sigan siendo válidos incluso si el repositorio se mueve o se replica en una plataforma diferente.

Forgejo opera bajo un calendario regular de lanzamientos, con versiones principales cada tres meses. Las versiones de Soporte a Largo Plazo (LTS) reciben mantenimiento extendido, mientras que las versiones estándar como la v17.0 tienen ventanas de soporte más cortas. Comprender este ciclo de vida ayuda a los equipos a planificar actualizaciones y parches de seguridad de manera efectiva. La versión LTS actual es la 15.0, soportada hasta julio de 2027, mientras que la v17.0 alcanzará su fin de vida útil en enero de 2027.

Por qué importa

Para equipos que gestionan su propia infraestructura de software, los cambios disruptivos en los webhooks representan un área de alto riesgo. Si una empresa depende de despliegues automatizados o actualizaciones de estado activadas por acciones de Forgejo, no migrar los webhooks puede detener los flujos de trabajo de desarrollo. A diferencia de las correcciones menores de errores, esta actualización requiere intervención activa: los administradores deben identificar todos los webhooks afectados, verificar que sus receptores puedan manejar la nueva estructura de payload y actualizar las configuraciones manualmente. No se proporciona ninguna herramienta automatizada para esta migración, lo que aumenta la carga operativa para los equipos de DevOps durante la ventana de actualización.

Las nuevas funciones organizacionales, como la membresía basada en invitaciones y las asignaciones masivas de equipos, abordan desafíos de escalabilidad para equipos en crecimiento. Anteriormente, añadir usuarios a múltiples equipos o gestionar grandes organizaciones requería pasos manuales repetitivos o scripting externo. Al integrar estas capacidades en la plataforma central, Forgejo reduce la necesidad de herramientas administrativas personalizadas. Además, la API mejorada para Actions permite un control más granular sobre los logs de trabajos y reejecuciones, facilitando una mejor depuración e integración de automatización para los líderes de ingeniería.

Qué puedes hacer

• Realiza una Copia de Seguridad de tu Instancia: Crea una copia de seguridad completa de tu instancia de Forgejo, incluyendo secretos y archivos de configuración, antes de intentar cualquier actualización.
• Audita los Webhooks: Identifica todos los webhooks que utilizan actualmente eventos de "action run" y documenta sus receptores y payloads esperados.
• Prueba en Preproducción: Utiliza la instancia de prueba dedicada en v17.next.forgejo.org o un entorno local de preproducción para verificar la compatibilidad de los webhooks con los nuevos eventos de workflow run.
• Actualiza la Configuración: Si utilizas invitaciones a organizaciones, actualiza tu archivo app.ini para establecer [service].ADD_MEMBERS_BY_INVITATIONS = true si lo deseas.
• Revisa las Referencias de Enlaces: Comprueba los repositorios de documentación para encontrar enlaces absolutos que puedan comportarse de manera diferente bajo las nuevas reglas de resolución.
• Planifica el Fin de Vida Útil: Ten en cuenta que el soporte para v17.0 termina el 28 de enero de 2027, y programa las actualizaciones subsiguientes a v18.0 o versiones LTS posteriores en consecuencia.