Forgejo v17.0 introduces breaking webhook changes and new collaboration tools

The Forgejo project released version 17.0 on 15 October 2026, marking a significant update for self-hosted Git forge administrators. This major release introduces several breaking changes, particularly affecting how webhooks handle action events, alongside new features for team management and code collaboration. Users are strongly advised to back up their instances and review migration guides before upgrading.

What happened

Forgejo v17.0 replaces the previous "action run" webhook events with more capable "workflow run" events. This shift is necessary because the older event structure was limited and problematic for complex CI/CD pipelines. The new workflow run events provide richer data and better alignment with modern automation standards. However, this transition is not automatic. Existing webhooks configured to listen for action runs will break if not updated, as headers like X-*-Event and the action key have changed significantly. Completion notifications are also now emitted only after all jobs in a run have terminated, altering the timing of alerts.

Beyond webhooks, the release adjusts how absolute links are rendered in documents. Links to resources inside a repository are now resolved relative to the repository root rather than the instance root. This change improves compatibility with other Git forges, making future migrations easier. Absolute links in issue descriptions and comments remain resolved against the instance root to preserve existing behavior in those contexts. These adjustments aim to standardize Forgejo’s behavior with broader ecosystem expectations while maintaining stability for user-facing content.

Key details

• Webhook Migration Required: Action run webhook events are deprecated and replaced by workflow run events; manual migration is required due to header and payload changes.
• Link Resolution Update: Absolute links in rendered documents now resolve relative to the repository root, improving cross-forge compatibility.
• Organization Invitations: Admins can enable invitation-based membership via app.ini, allowing users to accept or decline org invites sent by email.
• FUNDING.yml Support: Repositories and profiles with a FUNDING.yml file now display a "Donate" button in the web interface.
• LFS Improvements: Git Large File Storage support includes better navigation, pointer handling, and views to discover commits referencing specific LFS files.
• Support Timeline: Version 17.0 is a non-LTS release supported until 28 January 2027, following the project’s three-month major release cycle.

Background

Webhooks are automated messages sent from one application to another when a specific event occurs. In Git forges like Forgejo, webhooks often trigger CI/CD pipelines, chat notifications, or deployment scripts. When the structure of these messages changes—as seen in the shift from action run to workflow run events—receiving systems may fail to parse the data correctly. This is why manual inspection and testing are critical during major upgrades. Similarly, link resolution determines how URLs within markdown files are interpreted. Changing from instance-root to repository-root resolution ensures that links remain valid even if the repository is moved or mirrored to a different platform.

Forgejo operates on a regular release schedule, with major versions every three months. Long Term Support (LTS) releases receive extended maintenance, while standard releases like v17.0 have shorter support windows. Understanding this lifecycle helps teams plan upgrades and security patches effectively. The current LTS version is 15.0, supported until July 2027, while v17.0 will reach end-of-life in January 2027.

Why it matters

For teams running their own software infrastructure, breaking changes in webhooks represent a high-risk area. If a company relies on automated deployments or status updates triggered by Forgejo actions, failing to migrate webhooks can halt development workflows. Unlike minor bug fixes, this update requires active intervention: administrators must identify all affected webhooks, verify that their receivers can handle the new payload structure, and update configurations manually. There is no automated tool provided for this migration, increasing the operational burden on DevOps teams during the upgrade window.

The new organizational features, such as invitation-based membership and bulk team assignments, address scalability challenges for growing teams. Previously, adding users to multiple teams or managing large organizations required repetitive manual steps or external scripting. By building these capabilities into the core platform, Forgejo reduces the need for custom administrative tools. Additionally, the improved API for Actions allows for more granular control over job logs and reruns, enabling better debugging and automation integration for engineering leads.

What you can do

• Back Up Your Instance: Create a full backup of your Forgejo instance, including secrets and configuration files, before attempting any upgrade.
• Audit Webhooks: Identify all webhooks currently using "action run" events and document their receivers and expected payloads.
• Test in Staging: Use the dedicated test instance at v17.next.forgejo.org or a local staging environment to verify webhook compatibility with the new workflow run events.
• Update Configuration: If using organization invitations, update your app.ini file to set [service].ADD_MEMBERS_BY_INVITATIONS = true if desired.
• Review Link References: Check documentation repositories for absolute links that may behave differently under the new resolution rules.
• Plan for End-of-Life: Note that v17.0 support ends on 28 January 2027, and schedule subsequent upgrades to v18.0 or later LTS versions accordingly.