How to update Forgejo to version 16.0: complete guide

Introduction to Forgejo 16.0

Forgejo 16.0 is a lightweight self-hosted development platform designed to host Git repositories and facilitate collaboration on software projects. This version introduces numerous advanced features that improve repository management, notifications, pull request reviews, and integration with external systems.

This guide is useful for system administrators, developers, and project teams who want to make the most of the new features in Forgejo 16.0. The improvements introduced make the platform more flexible, secure, and powerful, allowing for more granular management of notifications, better organization of reviews, and more secure integration with external systems.

• Granularity of notifications: Allows you to select specific activities for notifications, reducing information noise.
• Improvements in migrations: Display of migration progress with detailed information on issues and pull requests transferred.
• Pull request reviews: New features for commenting on multiple lines simultaneously and a redesigned layout for better adaptability.
• Forgejo Actions: Manual prioritization of workflow runs and improvements in authentication via JWT.
• Improved API: New endpoints for managing logs and artifacts, with the ability to delete via web interface or HTTP API.
• Git Security: Verification of incoming objects to prevent repository corruption and improvements in hook management.

For more details, see the official announcement here.

Prerequisites

• Hardware: Server with at least 2 CPU cores, 4GB of RAM, and 20GB of disk space.
• Software: Linux operating system (Ubuntu 20.04 LTS, Debian 10, CentOS 7), Docker and Docker Compose, Git.
• Permissions: Root or sudo access for server installation and configuration.

Procedure for Upgrading to Forgejo 16.0

This guide will allow you to upgrade your Forgejo instance to version 16.0, benefiting from the new features and improvements described.

• Check the current version of Forgejo installed on your system.
• Perform a full backup of your database and the repositories hosted on Forgejo.
• Download the latest version of Forgejo 16.0 from the official site.
• Follow the specific instructions for your operating system to install the new version.
• Run the necessary upgrade commands for your execution environment.
• Verify that all Forgejo services are running correctly.
• Check the necessary configuration changes, especially if you use reverse proxy authentication.
• Explicitly configure the addresses or networks from which trusted reverse proxy traffic originates.
• Test all major Forgejo features to ensure the upgrade was successful.

Verification and Troubleshooting

At the end of this guide, you will be able to test the correct operation of Forgejo 16.0 and resolve any problems that may occur during use.

Functionality Testing

• Granular Notifications: Verify that notification options for repositories are configured correctly. Check that you receive notifications only for the selected activities (issues, pull requests, releases).
• Repository Migration: During a migration, ensure that the number of issues and pull requests transferred is displayed correctly. Verify that progress information appears for migrations with at least 45 items.
• Pull Request Reviews: Test the ability to attach a single comment to multiple modified lines by holding down Shift and selecting the desired range in the diff.
• PR Commit List: Check that the new commit list layout is visible and adaptable to different screen sizes.
• Review Comments: Verify that review comments are moved correctly when the code moves and are marked as obsolete if the associated line no longer exists.
• Forgejo Actions: Test the manual priority of workflow runs and ensure that priority runs are positioned before ordinary queue runs.
• Authorized Integrations: Verify that external integrations and local Forgejo Actions workflows can authenticate API and Git operations via verified JSON Web Tokens.
• Workflow Conditions: Check that workflow conditions are evaluated before sending jobs to a Forgejo Runner.
• Workflow Deletion: Test the deletion of completed workflow runs, including logs and artifacts, via the web interface or HTTP API.
• API: Verify that the new API endpoints for retrieving workflow logs and managing artifacts work correctly.
• Git: Check that incoming objects are verified for inconsistencies and that Git example hook files are no longer installed in backend repositories.

Troubleshooting

• Notifications Not Received: If you are not receiving notifications, verify that the notification options are configured correctly and that the notification backend is functioning.
• Interrupted Migration: If the migration is interrupted, check the number of items transferred and ensure that the system has enough resources to complete the migration.
• Lost Review Comments: If review comments are not moved correctly, verify that Git's reverse blame functionality is active and working.
• Workflow Priority Not Applied: If manual workflow priority is not applied, check that priority runs are configured correctly.
• Failed Authentication: If authentication via JSON Web Tokens fails, verify that integrations are authorized and that the tokens are valid.
• Non-Responsive API: If API endpoints do not respond, check that the server is active and that API requests are formulated correctly.
• Repository Corruption: If repository corruption occurs, ensure that incoming objects are verified for inconsistencies.
• Container Configuration: If using containers with reverse proxy authentication, ensure that the source addresses or networks of trusted proxy traffic are explicitly configured.

At the end of this guide, you will have a complete overview of the new features introduced in Forgejo 16.0 and know how to apply them in your development environment.

Educational Summary

• Granular notifications: Configure notifications to receive specific updates on issues, pull requests, releases, or a combination of these.
• Review comments: Use Git's reverse blame functionality to track changes more reliably.
• Workflow priority: Manually prioritize workflow runs to position them ahead of ordinary queues.
• Expanded API: Access new endpoints to retrieve complete workflow logs, list, download, and delete artifacts.

Call to Practice

To learn more about the new features of Forgejo 16.0, see the official announcement. If you are an administrator, make sure to review the breaking changes before proceeding with the upgrade.