Forgejo v17.0 giới thiệu các thay đổi webhook gây gián đoạn và công cụ cộng tác mới

Dự án Forgejo đã phát hành phiên bản 17.0 vào ngày 15 tháng 10 năm 2026, đánh dấu một bản cập nhật quan trọng dành cho các quản trị viên của nền tảng Git tự chủ (self-hosted). Bản phát hành chính này giới thiệu một số thay đổi gây gián đoạn, đặc biệt ảnh hưởng đến cách webhook xử lý các sự kiện action, cùng với các tính năng mới cho việc quản lý nhóm và cộng tác mã nguồn. Người dùng được khuyến nghị mạnh mẽ nên sao lưu các instance của mình và xem xét kỹ hướng dẫn di chuyển trước khi nâng cấp.

Chuyện gì đã xảy ra

Forgejo v17.0 thay thế các sự kiện webhook "action run" cũ bằng các sự kiện "workflow run" có khả năng tốt hơn. Sự chuyển đổi này là cần thiết vì cấu trúc sự kiện cũ bị hạn chế và gây ra vấn đề cho các pipeline CI/CD phức tạp. Các sự kiện workflow run mới cung cấp dữ liệu phong phú hơn và phù hợp hơn với các tiêu chuẩn tự động hóa hiện đại. Tuy nhiên, quá trình chuyển đổi này không diễn ra tự động. Các webhook hiện có được cấu hình để lắng nghe action runs sẽ bị lỗi nếu không được cập nhật, do các header như X-*-Event và khóa action đã thay đổi đáng kể. Thông báo hoàn tất cũng chỉ được gửi sau khi tất cả các job trong một run kết thúc, làm thay đổi thời điểm nhận cảnh báo.

Ngoài webhook, bản phát hành còn điều chỉnh cách hiển thị các liên kết tuyệt đối trong tài liệu. Liên kết đến các tài nguyên bên trong repository giờ đây được giải quyết tương đối so với gốc repository thay vì gốc instance. Thay đổi này cải thiện khả năng tương thích với các nền tảng Git forge khác, giúp việc di chuyển trong tương lai dễ dàng hơn. Các liên kết tuyệt đối trong mô tả issue và bình luận vẫn được giải quyết dựa trên gốc instance để duy trì hành vi hiện có trong các ngữ cảnh đó. Những điều chỉnh này nhằm mục đích chuẩn hóa hành vi của Forgejo theo kỳ vọng chung của hệ sinh thái rộng lớn hơn, đồng thời duy trì sự ổn định cho nội dung mà người dùng nhìn thấy.

Chi tiết chính

• Yêu cầu di chuyển Webhook: Các sự kiện webhook action run đã ngừng hỗ trợ và được thay thế bằng các sự kiện workflow run; việc di chuyển thủ công là bắt buộc do thay đổi về header và payload.
• Cập nhật giải quyết liên kết: Các liên kết tuyệt đối trong tài liệu được hiển thị giờ đây được giải quyết tương đối so với gốc repository, cải thiện khả năng tương thích giữa các nền tảng forge.
• Lời mời tham gia Tổ chức: Quản trị viên có thể bật tính năng thành viên dựa trên lời mời thông qua app.ini, cho phép người dùng chấp nhận hoặc từ chối lời mời tham gia tổ chức được gửi qua email.
• Hỗ trợ FUNDING.yml: Các repository và hồ sơ có tệp FUNDING.yml giờ đây hiển thị nút "Donate" (Quyên góp) trên giao diện web.
• Cải tiến LFS: Hỗ trợ Git Large File Storage bao gồm điều hướng tốt hơn, xử lý con trỏ (pointer) và các chế độ xem để khám phá các commit tham chiếu đến các tệp LFS cụ thể.
• Dòng thời gian hỗ trợ: Phiên bản 17.0 là bản phát hành không phải LTS, được hỗ trợ đến ngày 28 tháng 1 năm 2027, tuân theo chu kỳ phát hành chính ba tháng của dự án.

Bối cảnh

Webhook là các tin nhắn tự động được gửi từ ứng dụng này sang ứng dụng khác khi một sự kiện cụ thể xảy ra. Trong các nền tảng Git forge như Forgejo, webhook thường kích hoạt các pipeline CI/CD, thông báo chat hoặc script triển khai. Khi cấu trúc của các tin nhắn này thay đổi—như thấy trong sự chuyển đổi từ action run sang workflow run events—các hệ thống nhận có thể không phân tích đúng dữ liệu. Đây là lý do tại sao việc kiểm tra và thử nghiệm thủ công là rất quan trọng trong các lần nâng cấp lớn. Tương tự, việc giải quyết liên kết xác định cách các URL trong tệp markdown được diễn giải. Việc thay đổi từ giải quyết dựa trên gốc instance sang gốc repository đảm bảo rằng các liên kết vẫn hợp lệ ngay cả khi repository được di chuyển hoặc nhân bản sang một nền tảng khác.

Forgejo hoạt động theo lịch trình phát hành đều đặn, với các phiên bản chính cứ mỗi ba tháng. Các bản phát hành Hỗ trợ Dài hạn (LTS) nhận được bảo trì mở rộng, trong khi các bản phát hành tiêu chuẩn như v17.0 có cửa sổ hỗ trợ ngắn hơn. Hiểu rõ vòng đời này giúp các đội ngũ lên kế hoạch nâng cấp và vá lỗi bảo mật hiệu quả. Phiên bản LTS hiện tại là 15.0, được hỗ trợ đến tháng 7 năm 2027, trong khi v17.0 sẽ đạt trạng thái hết vòng đời (end-of-life) vào tháng 1 năm 2027.

Tại sao điều này quan trọng

Đối với các đội ngũ vận hành hạ tầng phần mềm riêng, các thay đổi gây gián đoạn trong webhook đại diện cho một khu vực rủi ro cao. Nếu một công ty phụ thuộc vào các triển khai tự động hoặc cập nhật trạng thái được kích hoạt bởi các action của Forgejo, việc không di chuyển webhook có thể làm đình trệ quy trình phát triển. Không giống như các sửa lỗi nhỏ, bản cập nhật này yêu cầu can thiệp tích cực: quản trị viên phải xác định tất cả các webhook bị ảnh hưởng, xác minh rằng các bộ thu (receiver) của họ có thể xử lý cấu trúc payload mới và cập nhật cấu hình thủ công. Không có công cụ tự động nào được cung cấp cho việc di chuyển này, làm tăng gánh nặng vận hành cho các đội DevOps trong thời gian nâng cấp.

Các tính năng tổ chức mới, chẳng hạn như thành viên dựa trên lời mời và gán nhóm hàng loạt, giải quyết các thách thức về khả năng mở rộng cho các đội ngũ đang phát triển. Trước đây, việc thêm người dùng vào nhiều nhóm hoặc quản lý các tổ chức lớn đòi hỏi các bước thủ công lặp đi lặp lại hoặc script bên ngoài. Bằng cách tích hợp các khả năng này vào nền tảng cốt lõi, Forgejo giảm bớt nhu cầu về các công cụ quản trị tùy chỉnh. Ngoài ra, API cải tiến cho Actions cho phép kiểm soát chi tiết hơn đối với nhật ký job và chạy lại (rerun), hỗ trợ gỡ lỗi tốt hơn và tích hợp tự động hóa cho các trưởng nhóm kỹ thuật.

Bạn có thể làm gì

• Sao lưu Instance của bạn: Tạo một bản sao lưu đầy đủ của instance Forgejo, bao gồm các bí mật (secrets) và tệp cấu hình, trước khi cố gắng thực hiện bất kỳ bản nâng cấp nào.
• Kiểm toán Webhook: Xác định tất cả các webhook hiện đang sử dụng sự kiện "action run" và ghi chép lại các bộ thu và payload mong đợi của chúng.
• Thử nghiệm trong môi trường Staging: Sử dụng instance thử nghiệm chuyên dụng tại v17.next.forgejo.org hoặc môi trường staging cục bộ để xác minh tính tương thích của webhook với các sự kiện workflow run mới.
• Cập nhật Cấu hình: Nếu sử dụng lời mời tham gia tổ chức, hãy cập nhật tệp app.ini của bạn để đặt [service].ADD_MEMBERS_BY_INVITATIONS = true nếu muốn.
• Xem xét Tham chiếu Liên kết: Kiểm tra các repository tài liệu để tìm các liên kết tuyệt đối có thể hoạt động khác nhau dưới các quy tắc giải quyết mới.
• Lên kế hoạch cho End-of-Life: Lưu ý rằng hỗ trợ cho v17.0 kết thúc vào ngày 28 tháng 1 năm 2027, và hãy lên lịch các bản nâng cấp tiếp theo sang v18.0 hoặc các phiên bản LTS sau đó cho phù hợp.