Forgejo v17.0 introduit des changements majeurs sur les webhooks et de nouveaux outils de collaboration

Le projet Forgejo a publié la version 17.0 le 15 octobre 2026, marquant une mise à jour significative pour les administrateurs de forges Git auto-hébergées. Cette version majeure introduit plusieurs changements cassants (breaking changes), affectant notamment la manière dont les webhooks gèrent les événements d'action, ainsi que de nouvelles fonctionnalités pour la gestion des équipes et la collaboration sur le code. Il est fortement recommandé aux utilisateurs de sauvegarder leurs instances et de consulter les guides de migration avant toute mise à niveau.

Ce qui s'est passé

Forgejo v17.0 remplace les anciens événements webhook « action run » par des événements « workflow run » plus performants. Ce changement est nécessaire car la structure des événements précédents était limitée et posait problème pour les pipelines CI/CD complexes. Les nouveaux événements de flux de travail offrent des données plus riches et une meilleure conformité aux normes modernes d'automatisation. Cependant, cette transition n'est pas automatique. Les webhooks existants configurés pour écouter les exécutions d'actions cesseront de fonctionner s'ils ne sont pas mis à jour, car les en-têtes tels que X-*-Event et la clé action ont changé de manière significative. De plus, les notifications de fin d'exécution ne sont désormais émises qu'une fois tous les jobs d'un run terminés, ce qui modifie le moment où les alertes sont déclenchées.

Au-delà des webhooks, la version ajuste la façon dont les liens absolus sont rendus dans les documents. Les liens vers les ressources situées dans un dépôt sont désormais résolus par rapport à la racine du dépôt plutôt qu'à la racine de l'instance. Ce changement améliore la compatibilité avec d'autres forges Git, facilitant ainsi les futures migrations. Les liens absolus dans les descriptions des tickets (issues) et les commentaires restent résolus par rapport à la racine de l'instance afin de préserver le comportement actuel dans ces contextes. Ces ajustements visent à standardiser le comportement de Forgejo avec les attentes plus larges de l'écosystème tout en maintenant la stabilité du contenu destiné aux utilisateurs.

Points clés

• Migration des Webhooks Requise : Les événements webhook « action run » sont dépréciés et remplacés par les événements « workflow run » ; une migration manuelle est nécessaire en raison des modifications des en-têtes et des charges utiles (payloads).
• Mise à Jour de la Résolution des Liens : Les liens absolus dans les documents rendus se résolvent désormais par rapport à la racine du dépôt, améliorant la compatibilité inter-forges.
• Invitations aux Organisations : Les administrateurs peuvent activer l'adhésion basée sur les invitations via app.ini, permettant aux utilisateurs d'accepter ou de refuser les invitations envoyées par e-mail.
• Prise en Charge de FUNDING.yml : Les dépôts et les profils contenant un fichier FUNDING.yml affichent désormais un bouton « Faire un don » dans l'interface web.
• Améliorations du LFS : La prise en charge de Git Large File Storage inclut une meilleure navigation, une gestion améliorée des pointeurs et des vues permettant de découvrir les commits référençant des fichiers LFS spécifiques.
• Calendrier de Support : La version 17.0 est une release non-LTS supportée jusqu'au 28 janvier 2027, conformément au cycle de publication majeure trimestrielle du projet.

Contexte

Les webhooks sont des messages automatisés envoyés d'une application à une autre lorsqu'un événement spécifique se produit. Dans les forges Git comme Forgejo, les webhooks déclenchent souvent des pipelines CI/CD, des notifications de chat ou des scripts de déploiement. Lorsque la structure de ces messages change — comme on le voit avec le passage des événements « action run » aux événements « workflow run » — les systèmes récepteurs peuvent échouer à analyser correctement les données. C'est pourquoi une inspection et des tests manuels sont critiques lors des mises à niveau majeures. De même, la résolution des liens détermine comment les URL dans les fichiers markdown sont interprétées. Passer d'une résolution relative à la racine de l'instance à une résolution relative à la racine du dépôt garantit que les liens restent valides même si le dépôt est déplacé ou dupliqué sur une plateforme différente.

Forgejo fonctionne selon un calendrier de publication régulier, avec des versions majeures tous les trois mois. Les versions Long Term Support (LTS) bénéficient d'une maintenance étendue, tandis que les versions standard comme la v17.0 ont des fenêtres de support plus courtes. Comprendre ce cycle de vie aide les équipes à planifier efficacement les mises à niveau et les correctifs de sécurité. La version LTS actuelle est la 15.0, supportée jusqu'en juillet 2027, tandis que la v17.0 atteindra sa fin de vie en janvier 2027.

Pourquoi c'est important

Pour les équipes gérant leur propre infrastructure logicielle, les changements cassants au niveau des webhooks représentent une zone à haut risque. Si une entreprise dépend de déploiements automatisés ou de mises à jour de statut déclenchés par les actions Forgejo, ne pas migrer les webhooks peut bloquer les workflows de développement. Contrairement aux corrections de bugs mineures, cette mise à jour nécessite une intervention active : les administrateurs doivent identifier tous les webhooks affectés, vérifier que leurs destinataires peuvent gérer la nouvelle structure de payload et mettre à jour les configurations manuellement. Aucun outil automatisé n'est fourni pour cette migration, augmentant la charge opérationnelle pour les équipes DevOps pendant la fenêtre de mise à niveau.

Les nouvelles fonctionnalités organisationnelles, telles que l'adhésion basée sur les invitations et l'affectation en masse d'équipes, répondent aux défis de scalabilité pour les équipes en croissance. Auparavant, ajouter des utilisateurs à plusieurs équipes ou gérer de grandes organisations nécessitait des étapes manuelles répétitives ou des scripts externes. En intégrant ces capacités directement dans la plateforme principale, Forgejo réduit le besoin d'outils d'administration personnalisés. De plus, l'API améliorée pour Actions permet un contrôle plus granulaire sur les logs des jobs et les relances, favorisant un meilleur débogage et une meilleure intégration d'automatisation pour les responsables techniques.

Que pouvez-vous faire ?

• Sauvegardez Votre Instance : Créez une sauvegarde complète de votre instance Forgejo, y compris les secrets et les fichiers de configuration, avant de tenter toute mise à niveau.
• Auditez les Webhooks : Identifiez tous les webhooks utilisant actuellement des événements « action run » et documentez leurs destinataires et les payloads attendus.
• Testez en Environnement de Préproduction : Utilisez l'instance de test dédiée sur v17.next.forgejo.org ou un environnement local de staging pour vérifier la compatibilité des webhooks avec les nouveaux événements de flux de travail.
• Mettez à Jour la Configuration : Si vous utilisez les invitations aux organisations, mettez à jour votre fichier app.ini pour définir [service].ADD_MEMBERS_BY_INVITATIONS = true si souhaité.
• Vérifiez les Références de Liens : Examinez les dépôts de documentation pour repérer les liens absolus qui pourraient se comporter différemment sous les nouvelles règles de résolution.
• Planifiez la Fin de Vie : Notez que le support de la v17.0 prend fin le 28 janvier 2027, et planifiez les mises à niveau ultérieures vers la v18.0 ou les versions LTS suivantes en conséquence.