Hoàng Lương Trần

ReleaseFlow

Biến pull request đã merge và issue đã xong thành release note có người duyệt, viết riêng cho từng nhóm người đọc.

Logo ReleaseFlow cùng tagline: release note đã được review cho từng audience, gửi đến đúng nơi họ đọc; nguồn GitHub, GitLab, Linear, Jira tới Slack, Email, Notion, Confluence, Teams, Zendesk

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.

Release v1.1.0 của project mẫu dbvault, có phụ đề tiếng Việt.

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.

Change Inbox với phần Đồng bộ nguồn cho một project Jira và hai repo, bên dưới là thay đổi DBV-44 kèm các nhãn
Hình 1. Change Inbox của một Project: trạng thái đồng bộ của các nguồn Jira, GitHub, GitLab, rồi tới từng thay đổi kèm nhãn category, review và loại khỏi release.

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:

  1. 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 CHANGE quyết định category (feature, fix, performance…). Kết quả luôn giải thích được vì sao.

  2. 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.

  3. 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ờ đó.

  4. 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.

Thẻ của pull request #25 trong Change Inbox với category Fix, lý do phân loại, danh sách file nhạy cảm và bản tóm tắt
Hình 2. Một thay đổi trong Change Inbox: category do rule chọn kèm lý do, các file nhạy cảm khiến nó phải được review, và bản tóm tắt trung lập do AI viế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.

Trang release v1.1.0 ở bước Đang review, với thanh tiến độ review và bản xem trước note theo từng audience
Hình 3. Release v1.1.0 đang review: chỉ phê duyệt được khi mọi thay đổi đã có quyết định; bên phải là bản xem trước note của từng audience.

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.

Note operator của release v1.1.0 với các tab theo audience và ngôn ngữ, bên cạnh là Markdown của note
Hình 4. Note đã publish của audience operator: mỗi audience và ngôn ngữ có một tab, kèm Markdown để copy hoặc tải về.

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.

Tin nhắn Slack chứa release note v1.1.0 với phần What’s New, New Features và Bug Fixes
Hình 5. Note của release v1.1.0 do một automation rule gửi vào Slack.

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

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.