The problem
Release notes are usually written by hand on release day: someone reads every merged pull request, guesses which ones matter, and writes one note. That note ends up too technical for users and too vague for the people who operate the software.
ReleaseFlow takes a different approach: it collects changes as they land, classifies them, lets AI draft the summaries, and keeps a person in charge of what goes out. Every step is recorded, so a published note always shows who reviewed what went into it.
How it works
Automating release notes does not mean putting them on autopilot, and it does not mean handing everything to AI. The work is really three different jobs:
-
Write — for each change: is it worth including, who needs to know, and how should it be explained to them.
-
Draft — assemble the chosen changes into one finished document, with the structure and format of the place it will appear.
-
Distribute — deliver that document to its readers through the right channel: a GitHub Release, Slack, email, a changelog page…
Drafting and distributing are repetitive, so ReleaseFlow automates them. Writing takes judgement: AI drafts, a person decides. In ReleaseFlow:
-
Rules and automation — classify and flag each change while writing; assemble, order and translate notes from templates while drafting; deliver each note to the right channel when distributing.
-
AI (optional) — only in writing: suggests a category, and writes a neutral summary and a narrative for each audience.
-
A person — decides at every step: approves or corrects each change, approves the release, edits a note if needed, and presses publish.
The video below is fifty seconds of a real release of a sample project: created, reviewed, approved, published, read on the public changelog without signing in, and posted to Slack.
Collect: changes arrive as they are merged
ReleaseFlow does not wait for release day. Each Project connects to one or more sources: merged pull requests from GitHub, merged merge requests from GitLab, and completed issues from Linear (by signed webhook) and Jira Cloud (by a scheduled poll). When first connected, GitHub and GitLab can import the last 90 days without ever duplicating a webhook delivery. Every change lands in the Project’s Change Inbox, so by release day most of the work has already been done along the way.
Write: rules classify, AI drafts, a person decides
For every new change:
-
Rules classify first. Conventional Commit titles, labels, documentation-only file lists and
BREAKING CHANGEfooters decide the category (feature, fix, performance…). The result can always be explained. -
AI drafts, if enabled. A single request to OpenAI, Anthropic or DeepSeek returns a suggested category, a neutral summary (what changed, why, technical detail, migration step) and a narrative for each audience, written to the communication intent that audience declares. The author’s name is never sent.
-
The rules always win. A category the rules chose is kept; the AI may mark a change breaking but can never clear the flag.
-
Anything doubtful waits for a person. Breaking, unrecognized and sensitive-file changes, changes with too little context or that look like an earlier one, and changes whose AI answer failed are all flagged with the evidence and must be reviewed.
Then a person does the judgement: approves or corrects the classification in the Change Inbox, rewrites a summary or narrative the AI got wrong (a summary a person wrote is never overwritten by AI), and excludes changes there is nothing to say about — an issue that duplicates the pull request that did the work, a fix and the revert that undid it — with a reason.
Each release moves through Draft → In review → Approved → Published. In review, every change needs a decision: keep it as shown, correct its classification, or reject it from the release. The release can be approved only once every change has a decision. Who reviewed each change, who approved, and who published are all recorded.
Draft: one note per audience, per language
When a release is approved, ReleaseFlow writes a note for every audience in every language. Each Organization starts with three preset audiences:
-
Operator — operational risk, rollback, what to watch.
-
Contributor — implementation detail and code changes.
-
End user — plain language, what people will notice.
You can add your own, up to 20. Each audience has a Mustache template that decides how a single change is presented, while the frame of the note stays the same: the release title and summary, a What’s New overview with counts, a warning if anything is breaking, then breaking changes first, followed by features, fixes, performance, documentation and maintenance.
Notes can be translated automatically by DeepL into up to five languages, and a release cannot be published until every translation is ready. Each note can be previewed before approval; after approval its Markdown can still be edited directly — the note is then marked Manual and no longer follows its template.
Distribute: the right note, the right channel, the right time
Publishing is the point of no return: every note is frozen, and PostgreSQL blocks any change to it, even through direct SQL. From there, automation rules handle delivery. Each rule has:
-
When it runs — when a release is published, when someone runs it by hand, on a cron schedule, a set time before a planned release (as an advance notice), or when another system calls it with a signed request.
-
What goes where — an ordered list of actions, each choosing the audience and language of the note it delivers: GitHub Releases, Slack, email, Notion, Confluence, Microsoft Teams, a Zendesk Help Center, or a public changelog with an RSS feed.
For example, a single rule can post the contributor note as the GitHub Release, send the operator note to the operations team’s Slack channel, and publish the Vietnamese end user note to a Zendesk Help Center and the public changelog — all from the same reviewed set of changes.
A delivery whose outcome could not be confirmed is never repeated without a person’s consent, so readers do not get the same note twice.
Technical decisions worth calling out
AI suggests; it never decides. Each change makes a single AI request. The answer is merged with the rules' result, and the rules take precedence. When the AI fails, nothing retries: the failure becomes a review trigger so a person looks at the change instead.
Shared-schema multi-tenancy. The Organization is the tenant boundary. Rather than a database or schema per tenant, every table shares one schema and isolation is applied explicitly in each query — simpler to migrate and to run (ADR-0001).
Background workers never hold a transaction while calling out. Five
scheduled workers do everything that talks to another system: enriching and
classifying changes, history imports, translation, and delivery. Each claims
its work with FOR UPDATE SKIP LOCKED in a short transaction, calls the
provider with no transaction open, and records the result in another short
transaction that first checks the claim is still its own. Workers never take
the same job twice, and stalled jobs are recovered safely.
The database protects the outcome. On top of service-layer checks, PostgreSQL constraints guarantee that a change still being processed cannot be released, reviewed or sent to AI. Flyway owns the schema; Hibernate only validates it.
No repeat without certainty. A delivery nobody could confirm is recorded as
UNKNOWN, kept apart from FAILED, and never repeated without a person’s
consent — it may already have arrived.
Secure by default. Webhook secrets, access tokens and action secrets are encrypted with AES-256-GCM. Every webhook is proven by an HMAC over the request itself. Four security filter chains divide the requests, and none of them switches CSRF protection off.
Quality and operations
It is a personal project, but I built it the way I would want a real product to be built:
-
More than 600 Java files, about 150 of them tests; integration tests run against a real PostgreSQL 17 through Testcontainers with the production migrations.
-
A Playwright browser and accessibility suite runs in CI.
-
CI includes CodeQL, dependency review, a full-history Gitleaks scan, and a Trivy image scan. Actions are pinned to commit SHAs and images to digests.
-
A tag is the release: its workflow publishes the JAR, the GHCR image, an SBOM, the quickstart bundle, checksums and provenance attestations.
-
The container runs as non-root; Prometheus metrics and health live on a separate management port that is never published.
-
33 Architecture Decision Records explain the reasoning behind each major choice.
-
A documentation site in English and Vietnamese, with a REST API reference checked against the code on every build.
How it compares
Tools such as release-drafter, git-cliff and semantic-release generate one changelog from commits or pull request labels, inside your repository or CI. They are simpler to adopt — if one technical changelog is all you need, use one of them.
ReleaseFlow is for the step after that: changes from several systems in one release, a review before anything is published, separate notes for separate readers in several languages, and delivery beyond the repository. The price is a server and a database to run.
Tech stack
| Layer | Technology |
|---|---|
Language / framework |
Java 21, Spring Boot 4 (Web MVC, Security, Data JPA, Validation, Mail) |
Interface |
Thymeleaf, Tailwind CSS 4, daisyUI 5, Alpine.js; in English or Vietnamese |
Database |
PostgreSQL, Flyway |
AI & translation |
OpenAI, Anthropic, DeepSeek (optional); DeepL (optional) |
Testing |
JUnit, Testcontainers, Playwright |
Packaging & CI |
Docker, GHCR, GitHub Actions |
Observability |
Spring Boot Actuator, Prometheus, Grafana |
Try it
The quickest way is the quickstart bundle attached to every release: the
published image and PostgreSQL on one machine, with nothing to build and no
repository to clone. You need Docker with Compose v2, and 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
Then open http://localhost:8080/register to create the first administrator.
Links
-
Documentation: hoangluongtran0309.github.io/ReleaseFlow
-
Changelog: CHANGELOG.md
ReleaseFlow is released under the Apache License 2.0. Feedback is the most useful contribution right now — how your team writes release notes today, and which sources or destinations are missing. Open a Discussion on GitHub.