Forgejo v17.0 führt Breaking Changes bei Webhooks und neue Kollaborationstools ein

Das Forgejo-Projekt hat am 15. Oktober 2026 die Version 17.0 veröffentlicht, was ein bedeutendes Update für Administratoren selbst gehosteter Git-Forges darstellt. Dieses Major Release führt mehrere Breaking Changes ein, die sich insbesondere darauf auswirken, wie Webhooks Action-Ereignisse behandeln, neben neuen Funktionen für Teamverwaltung und Code-Kollaboration. Benutzer werden dringend aufgefordert, vor dem Upgrade ihre Instanzen zu sichern und die Migrationsleitfäden zu prüfen.

Was passiert ist

Forgejo v17.0 ersetzt die vorherigen "action run"-Webhook-Ereignisse durch leistungsfähigere "workflow run"-Ereignisse. Diese Umstellung ist notwendig, da die ältere Ereignisstruktur für komplexe CI/CD-Pipelines begrenzt und problematisch war. Die neuen Workflow-Run-Ereignisse bieten umfangreichere Daten und eine bessere Übereinstimmung mit modernen Automatisierungsstandards. Dieser Übergang erfolgt jedoch nicht automatisch. Bestehende Webhooks, die auf Action Runs lauschen, brechen ab, wenn sie nicht aktualisiert werden, da sich Header wie X-*-Event und der Schlüssel action erheblich geändert haben. Auch Abschlussbenachrichtigungen werden nun erst ausgegeben, nachdem alle Jobs in einem Lauf beendet sind, was das Timing der Warnungen verändert.

Neben den Webhooks passt das Release auch an, wie absolute Links in Dokumenten gerendert werden. Links zu Ressourcen innerhalb eines Repositorys werden nun relativ zum Repository-Root aufgelöst, anstatt relativ zum Instanz-Root. Diese Änderung verbessert die Kompatibilität mit anderen Git-Forges und erleichtert zukünftige Migrationen. Absolute Links in Issue-Beschreibungen und Kommentaren werden weiterhin gegen den Instanz-Root aufgelöst, um das bestehende Verhalten in diesen Kontexten beizubehalten. Diese Anpassungen zielen darauf ab, das Verhalten von Forgejo mit den Erwartungen des breiteren Ökosystems zu standardisieren, während die Stabilität für benutzerseitige Inhalte gewahrt bleibt.

Wichtige Details

• Webhook-Migration erforderlich: Action-Run-Webhook-Ereignisse sind veraltet und werden durch Workflow-Run-Ereignisse ersetzt; aufgrund von Änderungen an Headern und Payloads ist eine manuelle Migration erforderlich.
• Update zur Linkauflösung: Absolute Links in gerenderten Dokumenten werden nun relativ zum Repository-Root aufgelöst, was die Cross-Forge-Kompatibilität verbessert.
• Organisations-Einladungen: Admins können die einladungsbasierte Mitgliedschaft über app.ini aktivieren, sodass Benutzer per E-Mail gesendete Org-Einladungen annehmen oder ablehnen können.
• FUNDING.yml-Unterstützung: Repositorys und Profile mit einer FUNDING.yml-Datei zeigen nun einen "Donate"-Button in der Weboberfläche an.
• LFS-Verbesserungen: Die Unterstützung für Git Large File Storage umfasst bessere Navigation, Pointer-Handling und Ansichten, um Commits zu finden, die spezifische LFS-Dateien referenzieren.
• Support-Zeitleiste: Version 17.0 ist ein Nicht-LTS-Release, das bis zum 28. Januar 2027 unterstützt wird, gemäß dem dreimonatigen Major-Release-Zyklus des Projekts.

Hintergrund

Webhooks sind automatisierte Nachrichten, die von einer Anwendung an eine andere gesendet werden, wenn ein bestimmtes Ereignis eintritt. In Git-Forges wie Forgejo lösen Webhooks oft CI/CD-Pipelines, Chat-Benachrichtigungen oder Deployment-Skripte aus. Wenn sich die Struktur dieser Nachrichten ändert – wie beim Wechsel von Action Run zu Workflow Run Events –, können empfangende Systeme scheitern, die Daten korrekt zu parsen. Deshalb sind manuelle Inspektion und Tests während großer Upgrades kritisch. Ebenso bestimmt die Linkauflösung, wie URLs innerhalb von Markdown-Dateien interpretiert werden. Der Wechsel von der Instanz-Root- zur Repository-Root-Auflösung stellt sicher, dass Links gültig bleiben, selbst wenn das Repository verschoben oder auf eine andere Plattform gespiegelt wird.

Forgejo arbeitet nach einem regelmäßigen Release-Zeitplan mit Major-Versionen alle drei Monate. Long Term Support (LTS)-Releases erhalten verlängerte Wartung, während Standard-Releases wie v17.0 kürzere Support-Zeiträume haben. Das Verständnis dieses Lebenszyklus hilft Teams, Upgrades und Sicherheitspatches effektiv zu planen. Die aktuelle LTS-Version ist 15.0, unterstützt bis Juli 2027, während v17.0 im Januar 2027 das End-of-Life erreicht.

Warum es wichtig ist

Für Teams, die ihre eigene Software-Infrastruktur betreiben, stellen Breaking Changes bei Webhooks ein Hochrisikogebiet dar. Wenn ein Unternehmen auf automatisierte Deployments oder Statusupdates angewiesen ist, die durch Forgejo-Actions ausgelöst werden, kann das Versäumnis, Webhooks zu migrieren, Entwicklungsworkflows stoppen. Im Gegensatz zu kleinen Bugfixes erfordert dieses Update aktives Eingreifen: Administratoren müssen alle betroffenen Webhooks identifizieren, überprüfen, ob ihre Empfänger die neue Payload-Struktur verarbeiten können, und die Konfigurationen manuell aktualisieren. Es wird kein automatisiertes Tool für diese Migration bereitgestellt, was die operative Belastung für DevOps-Teams während des Upgrade-Fensters erhöht.

Die neuen Organisationsfunktionen, wie einladungsbasierte Mitgliedschaft und Bulk-Team-Zuweisungen, adressieren Skalierbarkeits-Herausforderungen für wachsende Teams. Bisher erforderte das Hinzufügen von Benutzern zu mehreren Teams oder die Verwaltung großer Organisationen repetitive manuelle Schritte oder externes Scripting. Indem diese Fähigkeiten in die Kernplattform integriert werden, reduziert Forgejo die Notwendigkeit für benutzerdefinierte administrative Tools. Zusätzlich ermöglicht die verbesserte API für Actions eine granularere Kontrolle über Job-Logs und Reruns, was besseres Debugging und Automatisierungsintegration für Engineering-Leads erlaubt.

Was Sie tun können

• Instanz sichern: Erstellen Sie ein vollständiges Backup Ihrer Forgejo-Instanz, einschließlich Secrets und Konfigurationsdateien, bevor Sie ein Upgrade versuchen.
• Webhooks auditieren: Identifizieren Sie alle Webhooks, die derzeit "action run"-Ereignisse nutzen, und dokumentieren Sie deren Empfänger und erwartete Payloads.
• In Staging testen: Nutzen Sie die dedizierte Testinstanz unter v17.next.forgejo.org oder eine lokale Staging-Umgebung, um die Webhook-Kompatibilität mit den neuen Workflow-Run-Ereignissen zu verifizieren.
• Konfiguration aktualisieren: Wenn Sie Organisations-Einladungen nutzen, aktualisieren Sie Ihre app.ini-Datei, um [service].ADD_MEMBERS_BY_INVITATIONS = true zu setzen, falls gewünscht.
• Linkreferenzen prüfen: Überprüfen Sie Dokumentations-Repositorys auf Referenzen, um sicherzustellen, dass diese mit der neuen Auflösung funktionieren.