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 is too technical for
users and too vague for operators. ReleaseFlow collects the changes as they land,
classifies them, lets AI draft the summaries, and keeps a person in charge of what goes
out.
Releases: every published version and its artifacts are listed on the
Releases page, and the
changelog says what each one changed. What is not released yet is
recorded under [Unreleased]; to try it, run ReleaseFlow
from source or with the demo stack.
About ReleaseFlow
ReleaseFlow is named for the path every change takes
through it: from the moment a pull request is merged or an issue is finished, through
classification and a person's review, to a note written for each reader and delivered to
the place that reader already looks. Each step is recorded, so a published note always
shows who reviewed what went into it.
It is meant for teams that ship to more than one kind of reader — the people who operate
the software, the people who build on it, and the people who use it — and who want those
notes written from the same reviewed facts instead of rewritten by hand three times.
How it works
- Collect. Merged pull requests from GitHub, merged merge requests from GitLab, and
completed issues from Linear and Jira arrive by signed webhook or a scheduled poll.
GitHub and GitLab can also import the last 90 days.
- Classify. Explainable rules sort every change into a category. Optional AI
(OpenAI, Anthropic, or DeepSeek) writes a neutral summary and suggests a category,
but the rules always win, and breaking, security, unrecognized, or sensitive-file
changes always wait for a person.
- Review. A release moves from draft through a decision on every change to
approval. Changes with too little context, or that look like earlier ones, are flagged
with the evidence.
- Write. One note per audience (operators, contributors, end users, or your own),
from a Mustache template, in up to five languages translated by DeepL, with an
Organization glossary that keeps product terms as written. Security changes get a
section of their own, and a footer can link the comparison with the previous release
and the upgrade guide.
- Publish. Published notes are frozen, then delivered by automation rules to GitHub
Releases, Slack, email, Notion, Confluence, Microsoft Teams, Zendesk, or a public
changelog with an RSS feed.
It is self-hosted: one Java 21 / Spring Boot application and PostgreSQL, with an
English or Vietnamese interface.
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, and if one technical changelog is all you need, use one of them.
ReleaseFlow is for the step after that: changes from several systems (GitHub, GitLab,
Linear, Jira) in one release, a review and approval 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.
Quickstart
The quickest way to try a released version: the published image and PostgreSQL on one
machine, with nothing to build and no repository to clone. Every release attaches the
bundle, so this works from the first published release on; until then, use the
demo stack.
You need Docker Engine or Docker Desktop with Compose v2, and openssl, on Linux or
macOS. On Windows, run it inside WSL 2. The image is amd64 only, so Apple silicon runs it
under emulation; turn on Docker Desktop's Rosetta setting if it starts slowly.
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 # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
bash quickstart.sh
Then open http://localhost:8080/register to create the first administrator. To use
another port, choose it on the first run: RELEASEFLOW_HTTP_PORT=18080 bash quickstart.sh.
Keep the .env the script writes beside it. The database was created with its
password, and its key encrypts every stored webhook secret and access token. What the
script checks, how to turn on AI, the everyday Compose commands, and how to upgrade are in
Getting started. The bundle is for one machine, not
production: TLS, backups, and secret storage are a real deployment's own to bring, and
Deploying to production lists what that takes.
Run from source
You need JDK 21 (which ./mvnw finds through JAVA_HOME, or the javac on PATH) and
a dedicated PostgreSQL database. Maven and Node.js come with the build: the Maven Wrapper
downloads Maven, and the build downloads a pinned Node.js into node/ on first use.
export RELEASEFLOW_DB_URL=jdbc:postgresql://localhost:5432/releaseflow
export RELEASEFLOW_DB_USERNAME=releaseflow
export RELEASEFLOW_DB_PASSWORD='replace-with-a-local-secret'
export RELEASEFLOW_CREDENTIAL_MASTER_KEY="$(openssl rand -base64 32)" # keep this value
./mvnw spring-boot:run
Open http://localhost:8080/register to create the first Organization and its
administrator. Flyway creates the schema on startup. Everything else — AI, translation,
email, provider timeouts, the public changelog address — is optional and listed in
Configuration.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
