Release Notes Scrapper Action

Automatically generate structured release notes directly from your GitHub issues and pull requests.
Categorize changes, highlight contributors, and maintain consistent release documentation — all fully automated.

• Overview
• Motivation
• Quick Start
• Requirements
• Configuration
• Example Workflow
• Feature Tutorials
• Troubleshooting
• Developer & Contribution Guide
• License & Support

Overview

Release Notes Scrapper Action scans issues, pull requests, and commits to create categorized release notes for your project releases.
It groups changes by labels (e.g., “Bugfixes 🛠”, “New Features 🎉”) and extracts relevant content from PR descriptions or CodeRabbit summaries.

Key Benefits

• Fully automated release note generation
• Categorization by labels or issue hierarchy
• Built-in “Service Chapters” to detect missing or incomplete release notes
• Configurable templates and icons
• Smart duplicate detection

Motivation

Good documentation isn’t optional — it’s your project’s memory.
This Action was created to make structured release documentation effortless and consistent across teams.

👉 For the full background and design principles, see docs/motivation.md

Quick Start

Add the following step to your workflow to start generating release notes.

- name: Generate Release Notes
  id: release_notes_scrapper
  uses: AbsaOSS/generate-release-notes@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tag-name: "v1.2.0"
    chapters: |
      - {"title": "Breaking Changes 💥", "label": "breaking-change"}
      - {"title": "New Features 🎉", "label": "feature"}
      - {"title": "Bugfixes 🛠", "label": "bug"}

Example output snippet:

### New Features 🎉
- #23 _Feature title_ author is @root assigned to @neo developed by @morpheus in #24
  - Added support for multi-factor authentication.

### Bugfixes 🛠
- PR: #25 _Copy not allowed_ author is @dependabot[bot] assigned to @smith developed by @smith
  - File copy operation has been implemented.

#### Full Changelog
https://github.com/org/repo/compare/v1.1.0...v1.2.0

That’s it — the Action will:

1. Fetch all closed issues and PRs from latest till now.
2. Categorize them by labels.
3. Extract release note text and contributors.
4. Output a Markdown section ready for publishing.

Requirements

To run this action successfully, make sure your environment meets the following requirements:

Requirement	Description
GitHub Token	A GitHub token with permission to read issues, pull requests, and releases. Usually available as ${{ secrets.GITHUB_TOKEN }}.
Python 3.11+	The action internally runs on Python 3.11 or higher. If you’re developing locally or testing, ensure this version is available.
Repository Permissions	The action needs at least read access to issues and pull requests, and write access to create or update release drafts.
YAML Chapters Config	Each chapter must have a title and a label. Example: {"title": "Bugfixes 🛠", "label": "bug"}.

Configuration

Only a few inputs are required to get started:

Name	Description	Required	Default
GITHUB_TOKEN	GitHub token for authentication	Yes	-
tag-name	Target tag for the release	Yes	-
chapters	List of chapters and labels for categorization	No	-
verbose	Enable detailed logging	No	false

For the full input and output reference, see Configuration reference.
For how label → chapter mapping and aggregation works, see Custom Chapters Behavior.

Important: tag defined by tag-name must exist in the repository; otherwise, the action fails.

Example Workflow

You can integrate this Action with your release process.

Example — Manual Release Dispatch

name: "Create Release & Notes"
on:
  workflow_dispatch:
    inputs:
      tag-name:
        description: 'Existing git tag to use for this draft release. Syntax: "v[0-9]+.[0-9]+.[0-9]+". Ensure the tag is created and pushed before running.'
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate Release Notes
        id: notes
        uses: AbsaOSS/generate-release-notes@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag-name: ${{ github.event.inputs.tag-name }}
          chapters: |
            - {"title": "New Features 🎉", "label": "enhancement"}
            - {"title": "New Features 🎉", "label": "feature"}
            - {"title": "Bugfixes 🛠", "label": "error"}
            - {"title": "Bugfixes 🛠", "label": "bug"}
            - {"title": "Infrastructure 🚧", "label": "infrastructure"}
            - {"title": "Documentation 📚", "label": "documentation"}

      - name: Create Draft Release
        uses: softprops/action-gh-release@v2
        with:
          name: ${{ github.event.inputs.tag-name }}
          tag_name: ${{ github.event.inputs.tag-name }}
          body: ${{ steps.notes.outputs.release_notes }}
          draft: true

For more complex automation scenarios, see the examples folder.

Feature Tutorials

Each feature is documented separately — click a name below to learn configuration, examples, and best practices.

Feature	Scope	Description
Release Notes Extraction	Extraction	Core logic that scans descriptions to extract structured release notes (and optionally CodeRabbit summaries).
CodeRabbit Integration	Extraction	Optional extension to Release Notes Extraction, enabling AI-generated summaries when PR notes are missing.
Skip Labels	Filtering	Exclude issues/PRs carrying configured labels from all release notes.
Service Chapters	Quality & Warnings	Surfaces gaps: issues without PRs, unlabeled items, PRs without notes, etc.
Duplicity Handling	Quality & Warnings	Marks duplicate lines when the same issue appears in multiple chapters.
Tag Range Selection	Time Range	Chooses scope via tag-name/from-tag-name.
Date Selection	Time Range	Chooses scope via timestamps (published-at vs created-at).
Custom Row Formats	Formatting & Presentation	Controls row templates and placeholders ({number}, {title}, {developers}, …).
Custom Chapters	Formatting & Presentation	Maps labels to chapter headings; aggregates multiple labels under one title.
Issue Hierarchy Support	Formatting & Presentation	Displays issue → sub-issue relationships.
Verbose Mode	Diagnostics & Technical	Adds detailed logs for debugging.

Category legend (keep it consistent across docs)

• Extraction – how notes are gathered (core behavior).
• Filtering – what gets included/excluded.
• Quality & Warnings – health checks that keep releases clean.
• Time Range – how the release window is determined.
• Formatting & Presentation – how lines look.
• Diagnostics & Technical – tooling, logs, debug.

Troubleshooting

Common questions and quick pointers.

Symptom	Likely Cause	Where to Read More
Issue/PR missing from a chapter	Skip label applied	Skip Labels
Issue missing but its PR appears	No change increment detected for issue (no merged PR linkage)	Release Notes Extraction
Chapter heading is empty	No qualifying records OR duplicates suppressed	Custom Chapters
Expected duplicate not shown	duplicity-scope excludes that chapter category	Duplicity Handling
CodeRabbit section ignored	Manual release notes section already present OR support disabled	CodeRabbit Integration

More Q&A: see the Custom Chapters FAQ.

Developer & Contribution Guide

We love community contributions!

• Developer Guide
• Contributing Guide

Typical contributions include:

• Fixing bugs or edge cases
• Improving documentation or examples
• Adding new configuration options

License & Support

This project is licensed under the Apache License 2.0. See the LICENSE file for full terms.

Support & Contact

• Issues
• Discussions

Acknowledgements

Thanks to all contributors and teams who helped evolve this Action. Your feedback drives continuous improvement and automation quality.