Plugin: generator-changelog-md

import { Aside } from ‘@astrojs/starlight/components’;

Generates an enhanced Markdown CHANGELOG.md with commit grouping, PR/commit linkification, contributor sections, and optional entry archiving. Use it as a replacement for semrel’s built-in changelog writer when you need a richer format.

Installation

Binary

semrel plugin install @semrel/generator-changelog-md

semrel plugin install downloads the binary to .semrel/plugins/ and updates .semrel.lock. Commit .semrel.lock to pin the version for your team.

Docker

Pre-built, signed multi-platform images (linux/amd64, linux/arm64) are published on every release:

docker pull ghcr.io/semrels/generator-changelog-md:latest

Verify the image signature with cosign:

cosign verify ghcr.io/semrels/generator-changelog-md:latest \
  --certificate-identity-regexp 'https://github.com/SemRels/generator-changelog-md/.github/workflows/release.yml.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Configuration

commit_changelog: false   # skip built-in writer; plugin handles CHANGELOG.md

plugins:
  - uses: @semrel/condition-gitlab-ci
    phase: condition

  - uses: @semrel/generator-changelog-md
    phase: pre-tag          # must be pre-tag — runs before the tag, auto-committed by semrel
    args:
      keep_releases: "10"   # keep 10 full entries; older ones are summarised
      signature: "true"     # optional semrel.io footer, opt-in

  - uses: @semrel/provider-gitlab

How it works

semrel generates the release version and collects commits (SEMREL_CHANGELOG env var).
The generator-changelog-md plugin receives SEMREL_CHANGELOG and writes an enhanced CHANGELOG.md directly to disk (keep_releases > 0 required).
semrel auto-commits any modified tracked files (including CHANGELOG.md) before creating the git tag.
The tag points to the commit that includes the enhanced changelog.

Environment variables

Name	Required	Default	Description
`SEMREL_PLUGIN_KEEP_RELEASES`	Yes (to write to disk)	`0`	Number of releases to keep fully expanded. `0` = stdout only, nothing written to disk.
`SEMREL_PLUGIN_TEMPLATE`	no	built-in	Path to a custom Go template.
`SEMREL_PLUGIN_MAX_COMMITS`	no	`100`	Maximum commits to include.
`SEMREL_PLUGIN_GROUP_BY_TYPE`	no	`true`	Group commits by Conventional Commit type.
`SEMREL_PLUGIN_LINK_PRS`	no	`true`	Linkify `(#123)` PR references.
`SEMREL_PLUGIN_LINK_COMMITS`	no	`true`	Linkify 40-char commit SHAs.
`SEMREL_PLUGIN_SIGNATURE`	no	`false`	Append an opt-in footer linking to `https://semrel.io` after the generated release entry.
`SEMREL_PLUGIN_AI_DISCLOSURE`	no	`false`	Detect AI co-author trailers (e.g. `Co-authored-by: Copilot`) and append a badge to each AI-assisted commit line.
`SEMREL_PLUGIN_AI_DISCLOSURE_BADGE`	no	`🤖`	Badge appended to AI-assisted lines. Set to `[AI]` for plain-text environments.
`SEMREL_PLUGIN_AI_DISCLOSURE_SECTION`	no	`false`	Append a collapsible 🤖 AI-Assisted Contributions section listing all AI-co-authored commits (requires `SEMREL_PLUGIN_AI_DISCLOSURE=true`).
`SEMREL_PLUGIN_CHANGELOG_FILE`	no	`CHANGELOG.md`	Output file path.

When SEMREL_PLUGIN_SIGNATURE=true, the generated Markdown entry ends with:

---
*Generated by [semrel.io](https://semrel.io)*

Source

SemRels/generator-changelog-md