changelogforge

A release is ready, the pull requests are merged, and now someone has to turn that list into the changelog section readers will actually scan. changelogforge does that one job: it takes the merged pull requests for a release, sorts them into labelled groups, and renders the section as Markdown in a fixed, predictable shape.

• Grouping by label — each pull request joins the first label in group_order that it carries. The default order is feature, bugfix, documentation, maintenance, and you can supply your own list to rename, reorder, add, or drop groups. Matching is exact and case-sensitive.

• An other group — a pull request carrying none of the group labels lands in a final group whose heading is Other changes. Groups that end up empty are left out entirely, and the other group only appears when it has something in it.

• Stable ordering — groups follow group_order with the other group always last, and inside a group the pull requests are sorted by number ascending, so the same input always renders the same section.

• Exact Markdown — the version heading sits at heading_level (default 2) and group headings one level deeper. The result also returns the grouped structure itself, so a caller can render the same data another way.

Version and date are printed in the heading exactly as given; neither is parsed or reformatted. Pull request numbers must be unique across the list — a repeat is a validation error naming both occurrences, for example pull_requests[2].number duplicates pull_requests[0].number — and every other malformed field is likewise an error naming its path, with no partial section produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/changelogforge generate --input args.json
npx @reneturcios/changelogforge --version

args.json contains the full arguments object:

{
  "version": "1.2.0",
  "date": "2026-10-27",
  "pull_requests": [
    { "number": 7, "title": "Add export button", "labels": ["feature"] },
    { "number": 12, "title": "Fix crash on empty input", "labels": ["bugfix"] },
    { "number": 15, "title": "Tidy internals" }
  ]
}

labels defaults to [] per pull request, group_order to ["feature", "bugfix", "documentation", "maintenance"], and heading_level to 2. The rendered section is printed as JSON:

{
  "version": "1.2.0",
  "date": "2026-10-27",
  "groups": [
    { "group": "feature", "heading": "feature", "pull_requests": [{ "number": 7, "title": "Add export button" }] },
    { "group": "bugfix", "heading": "bugfix", "pull_requests": [{ "number": 12, "title": "Fix crash on empty input" }] },
    { "group": "other", "heading": "Other changes", "pull_requests": [{ "number": 15, "title": "Tidy internals" }] }
  ],
  "markdown": "## 1.2.0 (2026-10-27)\n\n### feature\n\n- Add export button (#7)\n\n### bugfix\n\n- Fix crash on empty input (#12)\n\n### Other changes\n\n- Tidy internals (#15)",
  "total_pull_requests": 3
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

Related MCP server: git-changelog

MCP server

npx -y @reneturcios/changelogforge mcp

MCP client config:

{
  "mcpServers": {
    "changelogforge": {
      "command": "npx",
      "args": ["-y", "@reneturcios/changelogforge", "mcp"]
    }
  }
}

Tools

• generate_changelog — Render a release changelog section from merged pull requests, grouped by label.

  • version (string, required) — release version label, printed verbatim in the heading

  • date (string, required) — release date, printed verbatim in the heading

  • pull_requests (array, required, at least one) — merged pull requests as {number, title, labels?} objects; number is unique across the list

  • group_order (array of strings, optional) — labels that define groups, in output order

  • heading_level (integer, optional, 1–5) — Markdown heading level for the version heading

  Returns {version, date, groups, markdown, total_pull_requests}.

Docker

docker run -i ghcr.io/cloudcorprecords/changelogforge
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/changelogforge generate --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios