What's included 🚀

Setup

Configure the workflow

-name:"Build Changelog"id:build_changeloguses:mikepenz/release-changelog-builder-action@{latest-release}

Important

When upgrading from v4 to v5, please ensure to read the upgrade warning in therelease notes, especially ifregexes are used.

Full Sample 🖥️

Action Inputs/Outputs

Action inputs

-name:"Complex Configuration"id:build_changelogif:startsWith(github.ref, 'refs/tags/')uses:mikepenz/release-changelog-builder-action@{latest-release}with:configuration:"configuration_complex.json"owner:"mikepenz"repo:"release-changelog-builder-action"ignorePreReleases:"false"fromTag:"0.3.0"toTag:"0.5.0"token:${{ secrets.PAT }}

Note

All input values are optional. It is only required to provide thetoken either via the input, or asenv variable.

Warning

${{ secrets.GITHUB_TOKEN }} only grants rights to the current repository, for other repositories please use a PAT (Personal Access Token).

Action outputs

# ${{steps.{CHANGELOG_STEP_ID}.outputs.changelog}}${{steps.build_changelog.outputs.changelog}}

Customization 🖍️

Note

Important

When running this action for non tags trigger thetoTag will be automatically resolved using the latest tag as retrieved by the git API.

Note

The first release tag is a special case since there is no previous release the action can reference to. For this case, there are two options:

1. When checking out the source viagit (E.g.:actions/checkout), the action will use the first commit.
2. Create an initial tag on the commit you want to begin a changelog from (for examplev0.0.1).

Note

By default not specifyingfromTag ortoTag will resolvetoTag from either theref or alternatively fallback to the latest tag from the git API.fromTag is resolved by sorting tags usingsemver. Tags not following semver are filtered out. Check theconfiguration for alternatives.

Note

If you are behind a corporate HTTP proxy, you can set thehttps_proxy environment variable to the proxy URL. For reference, please see the Octokitdocumentation.

Configuration

Note

Defaults for the configuration can be found in theconfiguration.ts

Note

It is possible to provide the configuration as file and as json via the yml file. The order of config values used:configurationJson >configuration >DefaultConfiguration.

{"categories": [      {"title":"## 🚀 Features","labels": ["feature"]      },      {"title":"## 🐛 Fixes","labels": ["fix"]      },      {"key":"tests","title":"## 🧪 Tests","labels": ["test"]      },      {"title":"## 🧪 Tests and some 🪄 Magic","labels": ["test","magic"],"exclude_labels": ["no-magic"],"exhaustive":true,"exhaustive_rules":"false","empty_content":"- no matching PRs","rules": [          {"pattern":"open","on_property":"status","flags":"gu"          }        ]      }    ],"ignore_labels": ["ignore"    ],"sort": {"order":"ASC","on_property":"mergedAt"    },"template":"#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>","pr_template":"- #{{TITLE}}\n   - PR: ##{{NUMBER}}","empty_template":"- no changes","label_extractor": [      {"pattern":"(.) (.+)","target":"$1","flags":"gu"      },      {"pattern":"\\[Issue\\]","on_property":"title","method":"match"      }    ],"duplicate_filter": {"pattern":"\\[ABC-....\\]","on_property":"title","method":"match"    },"reference": {"pattern":".*\\\\#(.).*","on_property":"body","method":"replace","target":"$1"    },"transformers": [      {"pattern":"[\\-\\*] (\\[(...|TEST|CI|SKIP)\\])( )?(.+?)\n(.+?[\\-\\*] )(.+)","target":"- $4\n  - $6"      }    ],"trim_values":false,"max_tags_to_fetch":200,"max_pull_requests":200,"max_back_track_time_days":365,"exclude_merge_branches": ["Owner/qa"    ],"tag_resolver": {"method":"semver","filter": {"pattern":"api-(.+)","flags":"gu"      }    },"base_branches": ["dev"    ]}

Warning

ignore_labels take precedence over category labels, allowing to specifically exclude certain PRs.

Template placeholders

PR Template placeholders

Important

v4 updates the default placeholders format to#{{}}. The old format${{}} will be supported until v5 for backwards compatibility.

Commit Template placeholders

Configuration Specification

Regex Configuration

Warning

Usages of\ in the json have to be escaped. E.g.\ becomes\\.

Custom placeholders

Gitea support 🧪

Warning

The API from gitea does not allow to retrieve thediff via its API, requiring the repo to be checked out

-name:Build Changeloguses:https://github.com/mikepenz/release-changelog-builder-action@v5with:platform:"gitea"# gitea or GitHub, default is GitHubconfiguration:"configuration.json"token:${{ secrets.GITEA_TOKEN }}

Contribute 🧬

# Install the dependencies$ npm install# Verify lint is happy$ npm run lint -- --fix# Build the typescript and package it for distribution$ npm run build&& npm run package# Run the tests, use to debug, and test it out$ npmtest

export GITHUB_TOKEN=your_personal_github_pat

Local Testing 🧪

npmtest -- -- demo.test.ts

Token Permission

GitHub actions

permissions:  contents: read  pull-requests: read

Fine-grained personal access tokens

Classic tokens

Developed By

Credits

Other actions

License

Copyright for portions of pr-release-notes are held by Nikolay Blagoev, 2019-2020 as part of project pull-release-notes.All other copyright for project pr-release-notes are held by Mike Penz, 2024.

Fork License

Copyright 2025 Mike PenzLicensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at   http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.

Sample result release notes / changelog