Skip to main content

Release Drafter

Release Drafter is a GitHub Action that automates the generation of release notes. It creates a draft release each time new code is pushed into your selected branch, updating the release notes based on the pull requests that have been merged since the last release. The tool aims to save time and effort by compiling a summary of changes, contributors, and other key information, which can be immediately published or further edited as needed.

This automated tool is highly configurable, allowing you to customize how your release notes should look, which changes should be included, and much more, all using a YAML configuration file stored in your repository.

Workflow​

The Release Drafter job runs as a GitHub action on each push to the main branch. It drafts a new release based on the changes since the last release using the release notes template provided in the .github/release-drafter.yml file.

A live example of the release notes generated by this action can be found on the Releases page of this repository.

Versioning scheme configuration​

The workflow supports two versioning schemes:

Choosing a versioning scheme​

To configure the versioning scheme, set the RELEASE_VERSION_SCHEME repository variable:

  1. Navigate to your repository on GitHub
  2. Go to Settings → Secrets and variables → Actions → Variables tab
  3. Click New repository variable
  4. Set Name to RELEASE_VERSION_SCHEME
  5. Set Value to:
    • calver - for Calendar Versioning (generates versions like 25.1.0)
    • Leave unset or use any other value for SemVer (default behavior)

How it works​

SemVer (default): When RELEASE_VERSION_SCHEME is not set or set to any value other than calver, Release Drafter uses its built-in version resolution to automatically increment versions based on pull request labels.

CalVer: When RELEASE_VERSION_SCHEME is set to calver, the workflow generates versions in YY.M.0 format based on the current date (e.g., 25.1.0 for January 2025, 25.12.0 for December 2025).

Release notes​

This template provides a .github/release-drafter.yml file with some sensible defaults to get you started. The file contains templates and configurations that Release Drafter uses to generate release notes.

name-template: '$RESOLVED_VERSION'
tag-template: '$RESOLVED_VERSION'
change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
version-resolver:
  default: minor
template: |
  ## What's new since $PREVIOUS_TAG

  $CHANGES

  **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...$RESOLVED_VERSION

  $CONTRIBUTORS

name-template: '$RESOLVED_VERSION'​

  • What it does: Specifies the template for the release name.
  • Variables: $RESOLVED_VERSION is a placeholder for the next version number. It defaults to the next version provided by the version-resolver.
  • Example: If the current latest version is 2.4.3 and the version-resolver returns minor, the next version would be 2.5.0, and the draft release name would be set as 2.5.0.

tag-template: '$RESOLVED_VERSION'​

  • What it does: Specifies the template for the Git tag to associate with the release.
  • Variables: $RESOLVED_VERSION is used here too.
  • Example: Similar to name-template, if the next version is 2.5.0 and the version-resolver returns minor, the Git tag would also be 2.5.0.

change-template: '- $TITLE @$AUTHOR (#$NUMBER)'​

  • What it does: Formats each individual change (merged pull request) that will be listed in the release notes.
  • Variables: $TITLE is the pull request title, $AUTHOR is the username of the person who created the pull request, and $NUMBER is the pull request number.
  • Example: If a pull request titled Fix bug was merged by Alice and its number was 42, the line in the release notes would be - Fix bug @Alice (#42).

change-title-escapes: '\<*_&'​

  • What it does: Escapes specific characters to prevent them from being parsed as Markdown or other formatting.
  • Characters: <, *, _, and & will be escaped.
  • Example: If a pull request title is Fix <bug> & improvements, it would be displayed as Fix \<bug\> \& improvements in the release notes.

version-resolver.default: minor​

  • What it does: Provides the default value returned by the version resolver. This allows to pass a version value via an environment variable, if required, to override automatically resolved version. In this way, the same template can be used to generate release notes by the Release Drafter action itself and any external tools (e.g. external GitHub action that creates a new version and passes it to the release drafter).
  • Defaults: minor sets the next resolved version to be a minor version.

template: |​

  • What it does: Sets the overall structure and layout of the generated release notes.

  • Variables: Various placeholders are used within this template to automatically populate data.

    • ## What's new since $PREVIOUS_TAG: Sets a header for what has changed since the last release.

      • Example: If the previous tag was 2.4.3, this would render as ## What's new since 2.4.3.

    • $CHANGES: Inserts all changes formatted according to change-template.

      • Example: If two pull requests were merged, you might see:

        - Fix bug @Alice (#42)
        - Add feature @Bob (#43)

    • **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...$NEXT_MINOR_VERSION: Creates a link to a page comparing the changes between the previous tag and the new version.

      • Example: The rendered URL might be https://github.com/owner/repo/compare/2.4.3...2.5.0.

    • $CONTRIBUTORS: Lists the contributors to this release.

      • Example: If Alice and Bob contributed, it would list: 
        Contributors: @Alice, @Bob