Automating GitHub Release Notes Classification with Release.yml and Release Drafter

If you have published projects on GitHub, you may know that GitHub can automatically generate Release Notes. The automatically generated notes can be simple and clear, but when the notes contain many entries, a flat list becomes hard to read.

Method 1: Use GitHub's Official Feature

This method relies on a configuration file .github/release.yml placed in the repository. The file works similarly to Issue and Pull Request templates and allows you to define categories, titles, and associated labels. An example configuration from the commit-check-action project looks like this:

changelog:
  exclude:
    labels:
      - ignore-for-release
  categories:
    - title: '🔥 Breaking Changes'
      labels:
        - 'breaking'
    - title: 🏕 Features
      labels:
        - 'enhancement'
    - title: '🐛 Bug Fixes'
      labels:
        - 'bug'
    - title: '👋 Deprecated'
      labels:
        - 'deprecation'
    - title: 📦 Dependencies
      labels:
        - 'dependencies'
    - title: Other Changes
      labels:
        - "*"

After adding .github/release.yml , GitHub will automatically group the generated Release Notes under the defined headings (e.g., 📦 Dependencies).

Method 2: Use Release Drafter

Release Drafter is a community‑maintained tool that uses a configuration file .github/release-drafter.yml . Its configuration offers more features, such as custom templates, sorting, replacers, and automatic labeling. The file can also be stored in a central repository under .github and shared across multiple projects.

An excerpt of a typical Release Drafter configuration is shown below:

_extends: .github

# Configuration for Release Drafter: https://github.com/toolmantim/release-drafter
name-template: $NEXT_MINOR_VERSION
tag-template: $NEXT_MINOR_VERSION
version-template: $MAJOR.$MINOR

# Emoji reference: https://gitmoji.carloscuesta.me/
categories:
  - title: 💥 Breaking changes
    labels:
      - breaking
  - title: 🚨 Removed
    labels:
      - removed
  - title: 🎉 Major features and improvements
    labels:
      - major-enhancement
      - major-rfe
  - title: 🐛 Major bug fixes
    labels:
      - major-bug
      - bug
      - bugfix
      - regression
      - regression-fix
  - title: 🌐 Localization and translation
    labels:
      - localization
  - title: 👷 Changes for plugin developers
    labels:
      - developer
  - title: 📝 Documentation updates
    labels:
      - documentation
  - title: 👻 Maintenance
    labels:
      - chore
      - internal
      - maintenance
  - title: 🚦 Tests
    labels:
      - test
      - tests
  - title: ✍ Other changes
  - title: 📦 Dependency updates
    labels:
      - dependencies
    collapse-after: 15
exclude-labels:
  - reverted
  - no-changelog
  - skip-changelog
  - invalid

template: |
$CHANGES

replacers:
  - search: '/\[*JENKINS-(\d+)\]*\s*-*\s*/g'
    replace: '[JENKINS-$1](https://issues.jenkins.io/browse/JENKINS-$1 "JENKINS-$1") - '
  - search: '/\[*HELPDESK-(\d+)\]*\s*-*\s*/g'
    replace: '[HELPDESK-$1](https://github.com/jenkins-infra/helpdesk/issues/$1 "HELPDESK-$1") - '
  - search: '/\[*SECURITY-(\d+)\]*\s*-*\s*/g'
    replace: '[SECURITY-$1](https://jenkins.io/security/advisories/ "SECURITY-$1") - '
  - search: '/\[*JEP-(\d+)\]*\s*-*\s*/g'
    replace: '[JEP-$1](https://github.com/jenkinsci/jep/tree/master/jep/$1 "JEP-$1") - '
  - search: '/CVE-(\d{4})-(\d+)/g'
    replace: 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2'
  - search: 'JFR'
    replace: 'Jenkinsfile Runner'
  - search: 'CWP'
    replace: 'Custom WAR Packager'
  - search: '@dependabot-preview'
    replace: '@dependabot'

autolabeler:
  - label: 'documentation'
    files:
      - '*.md'
    branch:
      - '/docs{0,1}\/.+/'
  - label: 'bug'
    branch:
      - '/fix\/.+/'
    title:
      - '/fix/i'
  - label: 'enhancement'
    branch:
      - '/feature\/.+/'
    body:
      - '/JENKINS-[0-9]{1,4}/'

The central configuration file .github/.github/release-drafter.yml used by Jenkins demonstrates advanced features such as templates, replacers, and automatic labeling. Reading the Release Drafter documentation is recommended to fully understand these capabilities.

Summary

Both methods can automatically categorize Release Notes by title. GitHub's native approach is simpler to set up and works for most projects but cannot read the configuration from a central .github repository. Release Drafter offers richer functionality—templates, sorting, replacers, and central configuration inheritance—making it a better fit for large open‑source organizations, while the native method suffices for personal projects.

Choose the solution that matches your project's scale and required features.