Changelog and GitHub Releases

tagpr delegates release-note generation to GitHub. It uses the Generate release notes API rather than implementing its own pull request categorization rules.

This provides a more useful starting point than copying raw Git history: pull request titles describe user-visible changes, labels can group them, and maintainers can review the result before release. tagpr converts the generated Markdown into a Keep a Changelog -style entry for the changelog file.

Generation flow

When generated notes are needed while tagpr prepares a release pull request, it calls GitHub with:

• the proposed next tag;
• the previous release tag, when one exists;
• the configured release branch; and
• the release-note configuration path.

GitHub returns generated release notes for the pull requests and contributors between the two versions. tagpr converts those notes into the changelog entry and includes the generated notes in the release pull request body where the template references .Changelog.

After the release pull request is merged, tagpr generates the notes again for the final tag when GitHub Release creation is enabled, and uses the returned title and body for the release. Generating the notes before creating the release also prevents the release pull request itself from being included as a released change.

Customize generated notes

GitHub reads .github/release.yml or .github/release.yaml by default. The file can define:

• changelog categories and the labels that place pull requests in them;
• labels and authors to exclude from release notes; and
• the label used for uncategorized changes.

See GitHub’s automatically generated release notes documentation for the complete schema.

If neither default file exists, tagpr creates this minimal configuration on its first run:

changelog:
  exclude:
    labels:
      - tagpr

The exclusion keeps tagpr’s own release pull request out of the generated change list.

Use a different configuration path

Set tagpr.releaseYAMLPath when each project in a monorepo needs its own release-note rules:

# tools/.tagpr
[tagpr]
    tagPrefix = tools
    changelogFile = tools/CHANGELOG.md
    releaseYAMLPath = tools/.github/release.yml

The path is relative to the repository root, not to the .tagpr file. If the configured file does not exist on the release branch, create and commit it before setting tagpr.releaseYAMLPath. Unlike the default .github/release.yml, a missing custom configuration path cannot be bootstrapped by the release pull request.

Control file and release creation

The generated notes are used in several places, while these settings control which artifacts tagpr writes:

• tagpr.changelog = false stops tagpr from creating or updating the changelog file.
• tagpr.changelogFile changes the changelog path from its default, CHANGELOG.md.
• tagpr.release = true creates a published GitHub Release.
• tagpr.release = draft creates a draft GitHub Release.
• tagpr.release = false creates the tag without creating a GitHub Release.

Release-note generation is demand-driven:

Therefore, setting tagpr.changelog = false and using a pull request template without .Changelog skips the Generate Release Notes API while preparing the pull request. Because .Changelog is evaluated lazily, references in unused definitions or conditional branches that are not executed do not call the API. Setting tagpr.release = false skips that API after merge as well. A parse or render failure in a configured template falls back to the built-in template, which references .Changelog and therefore still generates notes.

If release assets must be built after tagging, see Coordinating Immutable Releases before enabling immutable releases. It explains when to let tagpr prepare a draft and when to delegate release creation to another workflow.