Vấn đề
Release note thường được viết tay vào đúng ngày release: một người đọc lại mọi pull request đã merge, đoán xem cái nào quan trọng, rồi viết ra một bản note duy nhất. Bản đó vừa quá kỹ thuật với người dùng cuối, vừa quá mơ hồ với người vận hành hệ thống.
ReleaseFlow giải quyết bước đó theo cách khác: gom thay đổi ngay khi chúng xuất hiện, phân loại chúng, để AI soạn nháp phần tóm tắt, nhưng luôn để con người quyết định cái gì được phát hành. Mỗi bước đều được ghi lại, nên một release note đã publish luôn cho biết ai đã duyệt những gì nằm trong nó.
ReleaseFlow hoạt động thế nào
Tự động hoá release note không có nghĩa là bật chế độ lái tự động, cũng không có nghĩa là giao hết cho AI. Việc làm release note thật ra gồm ba phần rất khác nhau:
-
Viết — với từng thay đổi: có đáng đưa vào không, ai cần biết, và giải thích nó thế nào cho người đó.
-
Soạn — ghép các thay đổi đã chọn thành một tài liệu hoàn chỉnh, đúng cấu trúc và định dạng của nơi nó sẽ xuất hiện.
-
Phân phối — đưa tài liệu tới người đọc qua đúng kênh: GitHub Release, Slack, email, trang changelog…
Soạn và phân phối là việc lặp đi lặp lại, nên ReleaseFlow để máy làm. Viết là việc cần phán đoán: AI giúp soạn nháp, còn con người quyết định. Cụ thể, trong ReleaseFlow:
-
Rule và automation — phân loại và gắn cờ từng thay đổi khi viết; ghép note theo template, sắp xếp và dịch khi soạn; gửi note tới đúng kênh khi phân phối.
-
AI (tuỳ chọn) — chỉ ở bước viết: gợi ý category, viết tóm tắt trung lập và một đoạn narrative cho từng audience.
-
Con người — quyết định ở mọi bước: duyệt hoặc sửa từng thay đổi, phê duyệt release, sửa note nếu cần, và bấm publish.
Video dưới đây là 50 giây của một release thật trên một project mẫu: tạo, review, phê duyệt, publish, đọc trên public changelog mà không cần đăng nhập, và được gửi vào Slack.
Thu thập: thay đổi đến ngay khi được merge
ReleaseFlow không đợi tới ngày release. Mỗi Project nối với một hoặc nhiều nguồn: pull request đã merge từ GitHub, merge request từ GitLab, issue đã hoàn thành từ Linear (qua webhook có chữ ký) và Jira Cloud (poll định kỳ). Khi mới kết nối, GitHub và GitLab có thể import 90 ngày gần nhất mà không tạo bản trùng với webhook. Mọi thay đổi nằm trong Change Inbox của Project, nên khi tới ngày release, phần lớn việc đã được làm dần từ trước.
Viết: rule phân loại, AI soạn nháp, con người quyết định
Với mỗi thay đổi mới:
-
Rule phân loại trước. Tiêu đề theo Conventional Commits, label, danh sách file chỉ có tài liệu và footer
BREAKING CHANGEquyết định category (feature, fix, performance…). Kết quả luôn giải thích được vì sao. -
AI soạn nháp, nếu được bật. Một request duy nhất tới OpenAI, Anthropic hoặc DeepSeek trả về: gợi ý category, một bản tóm tắt trung lập (thay đổi gì, vì sao, chi tiết kỹ thuật, bước migrate) và một đoạn narrative cho từng audience, viết theo "communication intent" mà audience đó khai báo. Tên tác giả không được gửi đi.
-
Rule luôn thắng. Category do rule chọn được giữ nguyên; AI có thể đánh dấu một thay đổi là breaking nhưng không bao giờ gỡ được cờ đó.
-
Cái gì đáng ngờ thì chờ người. Thay đổi breaking, không nhận diện được, chạm vào file nhạy cảm, thiếu ngữ cảnh, giống một thay đổi trước đó, hoặc AI trả lời lỗi — đều bị gắn cờ kèm bằng chứng và bắt buộc phải được duyệt.
Sau đó con người làm phần phán đoán: duyệt hoặc sửa phân loại trong Change Inbox, viết lại tóm tắt hay narrative khi AI viết chưa đúng (bản do người viết không bao giờ bị AI ghi đè), và loại hẳn những thay đổi không cần kể — một issue trùng với pull request đã làm nó, một bản fix rồi bị revert — kèm lý do.
Mỗi release đi qua bốn trạng thái: Draft → In review → Approved → Published. Ở bước review, mỗi thay đổi phải nhận một quyết định: giữ nguyên, sửa phân loại, hoặc loại khỏi release. Chỉ khi mọi thay đổi đã có quyết định thì release mới được phê duyệt. Người duyệt từng thay đổi, người phê duyệt và người publish đều được ghi lại.
Soạn: một note cho mỗi audience, mỗi ngôn ngữ
Khi release được phê duyệt, ReleaseFlow viết một note cho mỗi audience trong mỗi ngôn ngữ. Mỗi Organization bắt đầu với ba audience mẫu:
-
Operator — rủi ro vận hành, cách rollback, cần theo dõi gì.
-
Contributor — chi tiết hiện thực và thay đổi trong code.
-
End user — ngôn ngữ đời thường, người dùng sẽ thấy gì khác.
Có thể thêm audience riêng, tối đa 20. Mỗi audience có một template Mustache quyết định từng thay đổi được trình bày thế nào, còn khung của note thì luôn giống nhau: tiêu đề và tóm tắt release, phần What’s New đếm số thay đổi, cảnh báo nếu có breaking change, rồi liệt kê breaking change trước, sau đó tới feature, fix, performance, tài liệu và bảo trì.
Note có thể được dịch tự động qua DeepL sang tối đa năm ngôn ngữ, và release chỉ publish được khi mọi bản dịch đã xong. Trước khi phê duyệt có thể xem trước từng note; sau khi phê duyệt vẫn có thể sửa thẳng Markdown của một note — note đó được đánh dấu Manual và không còn đi theo template nữa.
Phân phối: đúng note, đúng kênh, đúng lúc
Publish là điểm không quay lại: mọi note bị đóng băng, và PostgreSQL chặn mọi chỉnh sửa, kể cả bằng SQL trực tiếp. Sau đó automation rule lo việc gửi đi. Mỗi rule gồm:
-
Khi nào chạy — khi release được publish, khi có người bấm chạy, theo lịch cron, một khoảng thời gian trước một release đã lên lịch (để báo trước), hoặc khi hệ thống khác gọi tới bằng request có chữ ký.
-
Gửi gì, đi đâu — một chuỗi action chạy theo thứ tự, mỗi action chọn audience và ngôn ngữ của note nó gửi: GitHub Releases, Slack, email, Notion, Confluence, Microsoft Teams, Zendesk Help Center hoặc public changelog có RSS.
Ví dụ, chỉ một rule có thể đăng note contributor lên GitHub Release, gửi note operator vào kênh Slack của team vận hành, và đưa note end user bản tiếng Việt lên Help Center trên Zendesk cùng public changelog — tất cả từ cùng một bộ thay đổi đã được duyệt.
Một lần gửi mà không xác nhận được kết quả sẽ không bao giờ tự gửi lại nếu không có người đồng ý, để người đọc không nhận cùng một note hai lần.
Những quyết định kỹ thuật mình thấy đáng kể
AI chỉ là gợi ý, không phải người quyết định. Mỗi thay đổi chỉ gọi AI một lần. Kết quả được gộp với kết quả của rule, và rule luôn được ưu tiên. Khi AI lỗi, hệ thống không retry mà biến lỗi đó thành một review trigger để người xem lại.
Multi-tenant bằng shared schema. Organization là ranh giới tenant. Thay vì mỗi tenant một database hay một schema, mọi bảng dùng chung schema và việc cô lập được áp dụng tường minh ở từng truy vấn — đơn giản hơn để migrate và vận hành (ADR-0001).
Background worker không giữ transaction khi gọi ra ngoài. Năm worker chạy
theo lịch xử lý mọi việc cần gọi hệ thống khác: enrich và phân loại thay đổi,
import lịch sử, dịch, phân phối note. Mỗi worker nhận việc bằng
FOR UPDATE SKIP LOCKED trong một transaction ngắn, gọi provider khi không có
transaction nào mở, rồi ghi kết quả trong một transaction ngắn khác — sau khi
kiểm tra việc đó vẫn đang thuộc về mình. Nhờ vậy nhiều worker không bao giờ
xử lý trùng một job, và job bị treo được thu hồi an toàn.
Database tự bảo vệ trạng thái. Ngoài kiểm tra ở tầng service, các ràng buộc
trong PostgreSQL đảm bảo một thay đổi đang xử lý không thể bị release, duyệt
hay gửi cho AI. Flyway quản lý schema, Hibernate chỉ validate.
Không gửi lại khi không chắc. Một lần phân phối mà không ai xác nhận được kết
quả sẽ được đánh dấu UNKNOWN, tách biệt với FAILED, và không bao giờ được
lặp lại nếu không có người đồng ý — vì có thể nó đã đến nơi rồi.
Bảo mật là mặc định. Webhook secret, access token và secret của các action được mã hoá AES-256-GCM. Mọi webhook được xác thực bằng HMAC trên chính request. Bốn security filter chain chia request, và không chain nào tắt CSRF.
Chất lượng và vận hành
Đây là dự án cá nhân, nhưng mình làm nó theo cách mình muốn một sản phẩm thật được làm:
-
Hơn 600 file Java, trong đó khoảng 150 file test; integration test chạy trên PostgreSQL 17 thật qua Testcontainers với đúng các migration production.
-
Bộ test trình duyệt và accessibility bằng Playwright chạy trong CI.
-
CI có CodeQL, dependency review, Gitleaks quét toàn bộ lịch sử, Trivy quét image. Action được pin theo commit SHA, image theo digest.
-
Mỗi tag là một release: workflow publish JAR, image trên GHCR, SBOM, bundle quickstart, checksum và provenance attestation.
-
Image container chạy non-root; metrics Prometheus và health check nằm trên một management port riêng, không bao giờ public.
-
33 Architecture Decision Record ghi lại lý do đằng sau mỗi lựa chọn lớn.
-
Trang tài liệu song ngữ Anh – Việt, kèm tài liệu REST API được kiểm tra với code ở mỗi lần build.
So với các công cụ khác
Những công cụ như release-drafter, git-cliff hay semantic-release sinh một changelog từ commit hoặc label của pull request, ngay trong repo hoặc CI. Chúng dễ áp dụng hơn — nếu bạn chỉ cần một changelog kỹ thuật, hãy dùng chúng.
ReleaseFlow dành cho bước tiếp theo: thay đổi từ nhiều hệ thống trong cùng một release, có duyệt trước khi phát hành, note riêng cho từng nhóm người đọc bằng nhiều ngôn ngữ, và phân phối ra ngoài repo. Cái giá là phải chạy một server và một database.
Tech stack
| Lớp | Công nghệ |
|---|---|
Ngôn ngữ / framework |
Java 21, Spring Boot 4 (Web MVC, Security, Data JPA, Validation, Mail) |
Giao diện |
Thymeleaf, Tailwind CSS 4, daisyUI 5, Alpine.js; giao diện tiếng Anh hoặc tiếng Việt |
Database |
PostgreSQL, Flyway |
AI & dịch |
OpenAI, Anthropic, DeepSeek (tuỳ chọn); DeepL (tuỳ chọn) |
Test |
JUnit, Testcontainers, Playwright |
Đóng gói & CI |
Docker, GHCR, GitHub Actions |
Quan sát |
Spring Boot Actuator, Prometheus, Grafana |
Chạy thử
Cách nhanh nhất là dùng bundle quickstart đi kèm mỗi release: image đã publish
cùng PostgreSQL trên một máy, không cần build hay clone repo. Bạn cần Docker
với Compose v2 và openssl.
mkdir releaseflow && cd releaseflow
base=https://github.com/hoangluongtran0309/ReleaseFlow/releases/latest/download
curl -fsSL --remote-name-all "$base/compose.yaml" "$base/quickstart.sh" "$base/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
bash quickstart.sh
Sau đó mở http://localhost:8080/register để tạo tài khoản quản trị đầu tiên.
Liên kết
-
Tài liệu: hoangluongtran0309.github.io/ReleaseFlow
-
Changelog: CHANGELOG.md
ReleaseFlow được phát hành theo giấy phép Apache 2.0. Mình rất muốn nghe phản hồi: team bạn đang viết release note thế nào, còn thiếu nguồn hay đích phân phối nào — hãy mở một Discussion trên GitHub.