Hoang Luong Tran

ReleaseFlow

Turn merged pull requests and finished issues into release notes a person has reviewed, written for each audience.

The ReleaseFlow logo and tagline: reviewed release notes for every audience, delivered where they are read; GitHub, GitLab, Linear and Jira to Slack, Email, Notion, Confluence, Teams and Zendesk

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.

Release v1.1.0 of the sample project dbvault, with English captions.

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.

The Change Inbox with the Source sync panel for a Jira project and two repositories, and change DBV-44 with its badges below
Figure 1. The Change Inbox of a Project: the sync state of its Jira, GitHub and GitLab sources, then each change with its category, review and exclusion badges.

Write: rules classify, AI drafts, a person decides

For every new change:

  1. Rules classify first. Conventional Commit titles, labels, documentation-only file lists and BREAKING CHANGE footers decide the category (feature, fix, performance…). The result can always be explained.

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

  3. The rules always win. A category the rules chose is kept; the AI may mark a change breaking but can never clear the flag.

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

The card of pull request #25 in the Change Inbox with its Fix category, the reason for it, its sensitive files and its summary
Figure 2. A change in the Change Inbox: the category the rules chose and why, the sensitive files that require a review, and the neutral summary the AI wrote.

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.

The page of release v1.1.0 at the In review step, with the review progress and a preview of the note for each audience
Figure 3. Release v1.1.0 in review: it can be approved only once every change has a decision; on the right, a preview of each audience’s note.

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.

The operator note of release v1.1.0 with tabs per audience and language, and the note’s Markdown beside it
Figure 4. The published operator note: a tab for every audience and language, with the Markdown to copy or download.

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 Slack message carrying the v1.1.0 release note with its What’s New, New Features and Bug Fixes sections
Figure 5. The note of release v1.1.0, posted to Slack by an automation rule.

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.

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.