Changelog in CI/CD: Setting Up Generation from Commits

Why manual changelog generation breaks the release cycle

Before every release, the same procedure starts: the release owner opens the chat, issue history, and the list of merged branches to compile release notes.

Some changes are remembered only by their authors, some have already shipped in an adjacent release, and some no one remembers. The changelog is assembled manually from memory and fragments of discussions — and it is always missing lines.

The reason is not carelessness, but that the commit history is unreadable.

Messages like "fixed", "updated", "again" do not describe what changed for the user; when branches are merged, one message absorbs a dozen edits; small fixes go straight to the main branch and are not mentioned anywhere.

Without commit markup — prefixes, issue links, a "user-visible change" flag — there is no way to separate the significant from the routine.

Lost edits surface later. A customer reports new behavior, and the team cannot say which release it appeared in: support learns about changes last. Release delays grow — list reconciliation happens after the freeze, instead of being assembled continuously along with the code.

At the same time, changelog generation is the most mechanical part of a release: if the rules for forming entries are fixed and commit markup is checked automatically, the changelog is assembled from repository history without manual reconciliation. We'll break down how this is addressed and what to fix in the team's habits.

What automated changelog assembly provides

The changelog stops being a manual document written in haste before a release. If commit messages are typed according to Conventional Commits, the generator parses the history between two tags, sorts entries into sections, and publishes ready notes as a build artifact. The manual stage goes away — only proofreading the text before publication remains.

We verify the result by measurable indicators:

• Release preparation time — change reconciliation happens inside the build: generating notes takes about a minute instead of hours of manual reconciliation.
• Share of missed changes — the check does not allow a merge without a valid commit type, so undocumented edits are practically eliminated.
• Number of clarifying questions to the team — there is a single source: commit history with issue links, and any participant can see what entered the release and when.
• Release history — continuous: each tag has an immutable set of entries, and rollback relies on a specific range, not on a developer's memory.
• Release predictability — the date no longer depends on manual formatting: only code readiness shifts the release, not the text.
• Separation by type — fixes, new features, and breaking changes are in separate sections, and the consumer immediately assesses upgrade risks.

Each point is checked on a live pipeline: we enable the rule, ship a release, and compare two or three iterations by the same metrics, before and after.

Changelog assembly methods: comparing approaches

The source for the changelog becomes what already passes through the pipeline: commit messages, tracker issues, and merge tags into the main branch.

The generator here is secondary — it transfers into the text the discipline that already exists in the team and does not create it itself.

Therefore, choosing a method comes down to a trade-off between the precision of wording for the reader and the amount of manual work in each release.

Four options and their weaknesses

All approaches share one common limitation: the generator sees only marked-up data. If some changes come outside the main pipeline — hotfixes, migrations, dependency updates — they will not get into the changelog until a separate rule is created for them.

That is why the choice is rarely made once and for all: teams start with merge tags, and when manual refinement becomes greater than generation, they move to a hybrid scheme.

Stages of implementing changelog generation in the pipeline

The order of work is the same for both a monorepo and a set of separate repositories: first we bring the history to a machine-readable form, then we embed the changelog assembly step, and only after testing on a live release do we formalize the regulation. Below is how it looks stage by stage.

1. Repository history audit. We calculate the share of commits suitable for automatic parsing according to Conventional Commits, find branches with manually merged edits, and tags without annotations. The results show how much history needs to be normalized and where it is enough to start with the current release.
2. Markup scheme. We fix the change types — added, fixed, changed, removed, security — and the rule for what counts as a breaking change. This provides entry grouping and automatic selection of the next version number.
3. Build step setup. The step is triggered by a tag, collects the commit range between the previous and current tag, discards service and merge commits, and inserts issue links. The output is a changelog file in the release artifact.
4. Validation on a real release. We run it on one release in parallel with the manual description and check completeness: whether any changes were lost and whether noise got into the text.
5. Release regulation. We describe where the developer sets the change type, who edits the draft, and who approves publication.
6. Handover to the team. Template walkthrough, documentation, and support through two releases — after that, the team runs the process itself.

Configurations, regulations, and documentation as output

The documentation set here is not a report for the customer, but a working contour: an engineer who joins the project six months later can set up changelog generation without chatting with the author.

Therefore, the artifacts are stored in the same repository as the code and go through review in the same way as build configurations. Below is exactly what remains at the output.

• Build configurations — a steps file that fixes the order: build, checks, changelog generation, publication; the commit range and the version number calculation rule.
• Branching scheme — which branches get into the public changelog, where the release boundary is, and how a fix is marked when ported to the stable branch.
• Publication access policies — who is allowed to write to the protected branch and trigger a release, and which checks must pass beforehand.
• Changelog templates — templates by change type: new feature, fix, incompatible change, and service edits that do not get into the public list.
• Team instructions — how to phrase a commit message so that the changelog entry is readable without manual refinement, and what to do about an incorrect tag.
• Release regulation — the sequence from branch freeze to publication, with a separate rollback scenario if an entry was published with an error.
• A scheme for connecting generation to already working builds, including a dry run on historical commits without publication — it shows what the changelog would look like now.

Such a set is reviewed like code: a change to a template or selection rule is visible in history and can be rolled back with one revision, rather than restored from memory.

Case study: how manual work on a release was reduced

In one product project, releases were prepared manually: an engineer read through the commit history, compiled the changelog, labeled categories, and linked entries to issues.

A release took from four to six hours, and when switching to a two-week cadence, this time no longer fit into the team's schedule.

What it was like before automation

Out of more than forty commits, an average of seven to eight edits did not make it into the final list: some were lost during manual selection, and some were hidden in branches with non-obvious names.

A separate class of errors was "the change shipped silently": users learned about the new behavior only after updating, and handling a request began with the question "was this even in the release?".

What was changed and what was achieved

Commit messages were brought to the Conventional Commits format, format validation was placed at the change acceptance stage, and the changelog assembly itself was tied to the version tag.

The categories "added / changed / fixed" are derived from the commit type, issue links come from the message body, and the result does not require manual refinement.

Release preparation was reduced to fifteen to twenty minutes, and only proofreading the draft before publication remained manual. Lost edits were reduced to zero: the list is assembled from the full history, not from a memory-based selection.

The "change shipped silently" class of errors disappeared — across twelve consecutive releases, not a single change was missed.

What to do if the repository already has a chaotic history

A chaotic commit history means messages like "fix", "wip", "edits", dozens of merge commits, and branches named after developers.

A changelog generator on such history will produce a list that cannot be shown to users or support: noise will collect into one stream and will not be sorted by change type.

The tool here is not the main thing — the parsing rule can be enabled at any moment. Something else is being decided: where the adoption boundary is, from which messages are considered suitable, and what to do with what lies to the left of it.

A separate boundary is more often chosen: the build configuration sets a range — from a fixed tag to the current state — and everything older goes through a one-time manual review and lands in an archive section.

The choice of strategy comes down to three questions: how many branches are maintained simultaneously, whether commits are referenced externally, and whether the reader needs an archive section.

If at least one answer is "yes", the history must not be rewritten; we start with a starting cutoff or a boundary.

Common technical questions about build setup

Changelog autogeneration breaks not on commit parsing, but on repository structure and team habits. Below are technical doubts that surface after the draft assembly has already started working.

How should the changelog be maintained during parallel releases?

The release branch gets its own set of fragments, so support and mainline entries do not intersect. Only what entered a specific build gets into the changelog — based on the branch history, not a shared list.

Do issues without commits get into the changelog?

No, and that is expected. Manual operations and configuration edits are placed in a separate section that the team fills in itself: mixing them with automatic entries is not worth it, otherwise verifiability is lost.

Do branch conflicts break changelog assembly?

Generation runs as a separate step and does not block merging. If a conflict affects the changelog files themselves, priority is given to entries from the target branch — otherwise the release draft is overwritten. The rule is fixed in the configuration.

The team writes commits the way it is used to — do we need to retrain them?

A prefix convention and message validation on the build side are enough: an invalid format does not pass further. The transition takes a couple of weeks, then the habit takes hold on its own, and the changelog stops requiring manual editing.

Let's discuss the task and come back with an implementation plan

To keep the conversation on an engineering plane from the start, it is useful to gather project inputs in advance.

They determine the architecture of the solution: the changelog generation trigger point depends on the branching scheme, and the quality and readability of the final file depend on discipline in commit messages.

• Repositories and version control systems where an automatic changelog is needed: one shared repository or several independent ones, and whether there are mirrors and forks.
• Branching scheme and release tagging rules: by what criterion a build is considered a release, and whether tags are set manually or automatically.
• Commit message convention: fixed type and scope of change, flagging backward-incompatible edits, and who monitors compliance.
• Target file format: grouping by change type, a separate block for breaking changes, tracker issue links, and the language of wording.
• Where to publish the result: a file in the repository, a release artifact, a documentation page, or a message in the team channel.
• Access and restrictions: write permissions for protected branches, build keys, and rules for working in an isolated environment without external services.
• The person responsible for final proofreading and the procedure if a release is assembled from several branches at the same time.

With this set of inputs, we come back with a work estimate and an implementation plan: what we do in the first stage, how we validate the logic on commit history, and in what timeframe we bring the process to a regular mode. Describe the task in a convenient form — we will clarify the rest ourselves during the discussion.