Automatic Release Notes generation in CI/CD: setup

Manual Release Notes assembly: where the process breaks

When a changelog is assembled manually, it almost always lags behind the code. An engineer reads commits in Git, reconciles them with tracker tasks, and reconstructs the logic of the changes from memory. On the eve of a release, this turns into a separate block of work that no one planned.

Manual Release Notes assembly takes one or two engineers several hours — and all this time they are not working on the release itself.

Some changes are described from memory, some are carried over from a previous release, and errors in the release description accumulate from version to version.

Errors in a release description rarely look like outright lies. More often it is a forgotten migration, a task lost in a branch, or a breaking change that only the author of the edit knew about.

For support and external consumers, such gaps are opaque changes: they are learned about from incidents, not from the document.

Desync adds its own. While the description is being prepared from the main branch, several more edits land in the release branch, and the changelog captures a state that no longer exists.

The more people and branches in the project, the higher the labor costs for a release and the more often you have to recheck already written text.

We break down how this is closed by automatic Release Notes assembly right in the build and delivery pipeline.

Measurable effect: what changes after release automation

The first effect is visible when preparing a delivery: release notes are assembled from change history automatically, together with artifact build, rather than as a separate task at the end of the cycle.

Manual work is reduced to proofreading the draft — time from merging the last edit to a ready release description is measured in minutes.

The second metric is the share of manual edits in the final text. While descriptions are written manually, almost every line is rewritten; after automation, edits remain where wording for the client is needed — usually a few items per release.

The third is the number of missed changes. The type parsing rule picks up edits that reached the main branch without a label and puts them in the "other" section.

The counter of uncategorized changes works as a quality metric: it should be zero, otherwise a parsing error returns to the template.

A unified description format removes the question of what to write in the notes. The template fixes sections — new, fixed, changed — and a mandatory link to the task.

Support gets a list of changes for clients without separate analysis, and the text does not depend on who ran the release.

Finally, change control: the commit — task — version link remains in the notes as a trace. From it you can see what was included in the delivery and what was postponed, and it is clear where to roll back. This is what turns a release from a manual operation into a reproducible process.

Release Notes generation methods: comparison of approaches

The choice of approach is determined by how disciplined the change history is and who is responsible for the final text.

If commits are written according to a convention, parsing the change history yields a ready draft; if messages are arbitrary, a semi-automatic mode is needed, where grouping rules sort changes into sections, and a person confirms the wording. Below are real alternatives that are chosen at the start of implementation.

In practice, a hybrid is more often taken: automatic Release Notes generation assembles a draft by parsing change history, grouping rules sort it into sections, and description templates set a unified tone.

Semi-automatic mode remains only for disputed entries — this reduces manual work and preserves control over what users will see.

How we implement automatic generation: stages of work

Implementation starts not with code, but with an inventory of how the team already maintains change history. Until the difference between branches, tags, and message formatting is visible, any automation will produce a junk changelog.

Below is a sequence of steps after which release entries are assembled automatically and remain readable.

1. Audit of repositories and current changelog. We look at branching, tag scheme, merge history, and how entries are currently formatted manually. The output is a map of repositories and a list of places where messages are unsuitable for parsing.
2. Message parsing rules. We agree on the format: change type, affected area, brief description. We fix the correspondence of types to changelog sections — new features, fixes, breaking changes.
3. Templates and grouping. We configure which entries go into the release, in what order sections appear, and what is discarded as service information. The template sets the structure and unified tone of wording.
4. Build pipeline setup. We embed the generation step into the existing process: the changelog is formed by the release tag and lands in artifacts before publication. For maintenance branches, we separately set the range of changes.
5. Check on a test release. We run it on a release candidate and compare the result with the manual version of the changelog. We make edits to the rules before the format is fixed for the team.
6. Documentation handover. We provide a description of the rules, the template, instructions for adding new types, and a breakdown of typical build failures. After that — targeted improvements as processes change.

The order matters: rules written before the audit almost always have to be rewritten — and generation enabled before testing on a real release breaks not the changelog, but the release process itself.

What we hand over: configurations, templates, regulations

We hand over the project not at the moment the build worked, but when the customer's team edits Release Notes itself, without us. Therefore, what is handed over is not a script, but a set of artifacts, each of which covers its own area of responsibility.

• Generator configuration — rules for forming the description: from which branches and tags history is taken, which change types go into the "new", "fixes", "breaking changes" sections, and which are discarded. An edit takes minutes and does not require code changes.
• Release description templates — blanks for a planned release, hotfix, and major update. The set of sections matches how the product is described in support and documentation, so the text does not have to be rewritten manually.
• Publication rights scheme — who assembles the draft, who approves, who publishes. Separation by roles and access tokens: the right to edit release text does not open access to the entire repository.
• Release preparation regulation — the order of steps from closing tasks to publication, with explicit points of human involvement: checking wording, section order, mandatory marking of breaking changes.
• Instructions for the team — how to add a section to the template, how to mark a change so it goes into the right group, and what to do if the generator fails: the draft is saved, publication of the ready release is not blocked.
• Integration map — where the ready description goes: task system, documentation portal, support notification channel. With the owner and access specified for each direction.
• Set of checks — running the generator on a copy of repository history: you can see how it will work on old tags and branches before enabling it in the main process.

We hand over each artifact with a short note on why it is needed and what will break if it is not maintained.

Case: how we cut release description preparation from hours to minutes

How it was

Release once every two weeks, and preparing the change description consumed almost a full working day for the team: an engineer manually read through the change history, reconciled it with tasks in the tracker, and marked it by type.

The output was a list of 40-60 lines, in which incompatible changes were consistently lost, and half of the wording was rewritten after review.

What we changed

Description assembly was moved directly into the build line: the step groups changes by type (new, fix, incompatible, internal), pulls task titles from GitLab, and forms a draft by the time the build is ready.

A separate rule discards service edits and test changes, so only what the user sees goes into the text. The release manager only has to proofread, not assemble from scratch.

What became

• Release preparation time: from 5-6 hours to 20-30 minutes, and the task stopped being blocking — the draft is ready before the build.
• Share of manual edits: about 10% of lines, and these are wording clarifications, not rewriting the entire history.
• Eliminated errors: missed incompatible changes, duplicate items, and broken task links.

The description is now assembled from the same source as the build itself, so there are no discrepancies between the text and the contents of the release. Users stopped learning about breaking changes after updating, and support stopped handling identical requests.

How does pipeline generation differ from a manual changelog?

A manual changelog rests on people's discipline: someone remembers what went into the release, someone reconciles wording, someone checks whether an item was lost. While there are few branches and participants, this works.

But the more parallel edits there are, the higher the chance that not everything makes it into the changelog, and the description diverges from what actually went into the release.

Generation from change history is built on fact: the tool reads commit history and version tags, groups entries by type, and assembles a draft exactly from what went into the build.

Nothing needs to be recalled after the fact — the list forms itself, and the discrepancy between changelog and code goes away as a class of errors.

The difference between approaches is in the source of truth: a manual changelog relies on memory and an agreement on style, while automatic relies on machine selection.

The first gives polished presentation, but scales poorly and breaks when the team composition changes; the second gives completeness, but writes the way the developers themselves formulate messages.

That is why the choice of method is rarely binary.

The hybrid mode is arranged as follows: the pipeline assembles a draft from change history, and the editor manually edits wording and adds what is not in the commits — the reason for the decision, known limitations, rollback order. Completeness comes from automation, presentation comes from a human.

The entry point to such a mode is an agreement on commit naming and type labels: then entries are sorted into sections without manual sorting. Then the rule is fixed in the pipeline, and Release Notes stop being a separate task that depends on who remembered about the release.

Doubts and technical limitations: common questions

The questions below come up in almost every setup: what to do with commits without a unified format, how not to expose internal edits, what happens if publication fails.

The answers describe the behavior that we set by default — all we need from you is a decision on which rules to adopt.

How to exclude internal edits from the public list?

Service tasks, test edits, and refactoring are marked at merge and do not go into the public list. The set of exclusions lives in the configuration, so it changes without rewriting the build.

How does this work in a monorepo?

Changes are grouped by component directories, and notes are assembled separately for each. Edits at the root go into a summary section — otherwise they are lost between service releases.

Can automation be rolled back if a note went out with an error?

Publication is moved to a separate step after artifact build, so it can be disabled with one line. An already published note is edited or republished, and the change history remains available.

What about publication to external systems?

Sending goes as a separate step with the external system's response saved. If it is unavailable, the step is retried, and the release is not blocked: the note is already assembled and lies in the build artifacts.

Tell us about the task — we'll come back with an estimate and plan

To come back with an estimate and work plan, we need not a detailed document, but the outline of the task: where the code lives, how the release is formed, and at what point the team currently sits down to write Release Notes manually.

This is enough to propose a scheme, name timelines, and show where automation will cover manual work.

What we need from you at the input:

• access to repositories with read rights and to the build system — at the first stage, a role without write access is enough;
• list of publication points: releases section in the repository, project wiki, task tracker, team channel, or external portal for customers;
• versioning rules and tag format — they define the boundary between releases;
• an agreed template: which blocks are mandatory — new, fixes, incompatible changes, known limitations;
• the name of the responsible person who approves the text before publication, and the procedure for manual editing;
• two or three examples of past releases — from them we will match tone and structure.

The first step is a pilot on one repository. We run the rules on already released versions, compare the result with the texts the team wrote manually, and show discrepancies.

If the picture matches expectations, we roll out to the remaining projects and add checks for changes that are easy to lose during manual selection.

Describe the task in two or three sentences — we'll come back with an estimate, work plan, and first step.