Awesome

What's included 🚀

• Super simple integration
  • ...even on huge repositories with hundreds of tags
• Parallel releases support
• Rich changelogs based on PRs
  • Alternative commit based mode
• Blazingly fast execution
• Supports any git project
• Highly flexible configuration
• Lightweight
• Supports any branch
• Rich build log output

Setup

Configure the workflow

Specify the action as part of your GitHub actions workflow:

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

[!IMPORTANT]
When upgrading from v4 to v5, please ensure to read the upgrade warning in the release notes, especially if regexes are used.

Full Sample 🖥️

Below is a complete example showcasing how to define a build, which is executed when tagging the project. It consists of:

• Prepare tag, via the GITHUB_REF environment variable
• Build changelog, given the tag
• Create a release on GitHub - specifying body with a constructed changelog

name: 'CI'
on:
  push:
    tags:
      - '*'

jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Build Changelog
        id: github_release
        uses: mikepenz/release-changelog-builder-action@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: mikepenz/action-gh-release@v0.2.0-a03 #softprops/action-gh-release
        with:
          body: ${{steps.github_release.outputs.changelog}}

jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Build Changelog
        uses: mikepenz/release-changelog-builder-action@v5
        with:
          configurationJson: |
            {
              "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>",
              "categories": [
                {
                    "title": "## 💬 Other",
                    "labels": ["other"]
                },
                {
                    "title": "## 📦 Dependencies",
                    "labels": ["dependencies"]
                }
              ]
            }
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  release:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - name: Build Changelog
        uses: mikepenz/release-changelog-builder-action@v5
        with:
          mode: "COMMIT"
          configurationJson: |
            {
              "template": "#{{CHANGELOG}}",
              "categories": [
                {
                    "title": "## Feature",
                    "labels": ["feat", "feature"]
                },
                {
                    "title": "## Fix",
                    "labels": ["fix", "bug"]
                },
                {
                    "title": "## Other",
                    "labels": []
                }
              ],
              "label_extractor": [
                {
                  "pattern": "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\\([\\w\\-\\.]+\\))?(!)?: ([\\w ])+([\\s\\S]*)",
                  "target": "$1"
                }
              ]
            }
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This example defines a regex to extract the label from the commit message. Handling flags from the Conventional Commit Standards.

Action Inputs/Outputs

Action inputs

Depending on the use-case additional settings can be provided to the action

- name: "Complex Configuration"
  id: build_changelog
  if: 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 the token either via the input, or as env variable.

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

Action outputs

After action execution it will return the changelog and additional information as step output. You can use it in any follow-up step by referencing the output by referencing it via the id of the step. For example build_changelog.

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

A full set list of possible output values for this action.

Customization 🖍️

Note

[!IMPORTANT]
When running this action for non tags trigger the toTag 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 via git (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 example v0.0.1).

[!NOTE]
By default not specifying fromTag or toTag will resolve toTag from either the ref or alternatively fallback to the latest tag from the git API. fromTag is resolved by sorting tags using semver. Tags not following semver are filtered out. Check the configuration for alternatives.

[!NOTE]
If you are behind a corporate HTTP proxy, you can set the https_proxy environment variable to the proxy URL. For reference, please see the Octokit documentation.

Configuration

The action supports flexible and extensive configuration options to fine-tune it for the specific projects needs. To do so provide the configuration either directly to the step via configurationJson or as file via the configuration.

- name: Build Changelog
  uses: mikepenz/release-changelog-builder-action@v5
  with:
    configurationJson: |
      {
        "template": "#{{CHANGELOG}}\n\n<details>\n<summary>Uncategorized</summary>\n\n#{{UNCATEGORIZED}}\n</details>",
        "categories": [
          {
              "title": "## 💬 Other",
              "labels": ["other"]
          }
        ]
      }

- name: "Build Changelog"
  uses: mikepenz/release-changelog-builder-action@{latest-release}
  with:
    configuration: "configuration.json"

[!WARNING]
It is required to have a checkout step prior to the changelog step if configuration is used, to allow the action to discover the configuration file. Use configurationJson as alternative.

[!NOTE]
Defaults for the configuration can be found in the configuration.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.

The configuration is a JSON in the following format. (The below showcases example configurations for all possible options. In most scenarios most of the settings will not be needed, and the defaults will be appropriate.)

{
    "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"
    ]
}

Any section of the configuration can be omitted to have defaults apply.

[!WARNING]
ignore_labels take precedence over category labels, allowing to specifically exclude certain PRs.

Please see the Configuration Specification for detailed descriptions on the offered configuration options.

Template placeholders

Table of supported placeholders allowed to be used in the template and empty_template (only supports placeholder marked for empty) configuration, to give additional control on defining the contents of the release notes / changelog.

PR Template placeholders

Table of supported placeholders allowed to be used in the pr_template configuration, which will be included in the release notes / changelog.

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

Table of special array placeholders allowed to be used in the pr_template configuration.

Array placeholders follow the following format: (KEY)[(*/index)] for example: ASSIGNEES[*] or ASSIGNEES[0]. When using * values are joined by ,.

Additionally, there are special array placeholders like REVIEWS which allows access to it's properties via (KEY)[(*/index)].(property).

For example: REVIEWS[*].author or REVIEWS[*].body

Similar to REVIEWS, REFERENCED PRs also offer special placeholders.

Configuration Specification

Table of descriptions for the configuration.json options to configure the resulting release notes / changelog.

Regex Configuration

Since v5.x or newer, the regex configuration was unified to allow the same functionalities to be used for the various use-cases. This applies to all configurations outlined in Configuration Specification and Custom placeholders that allow a regex object.

Sample extracts a ticket number from the title

Sample PR title input

[XYZ-1234] This is my PR title

Regex replace pattern

{
  "name": "TICKET",
  "source": "TITLE",
  "transformer": {
    "pattern": "\\s*\\[([A-Z].{2,4}-.{2,5})\\][\\S\\s]*",
    "target": "- [$1](https://corp.ticket-system.com/browse/$1)"
  }
}

Regexr style pattern (Use regexr.com to test). To test on Regexr inverse the escaping of \\ to \

{
  "name": "TICKET",
  "source": "TITLE",
  "transformer": {
    "pattern": "\\[([A-Z]{2,4}-.{2,5})\\]",
    "method": "regexr",
    "target": '- [$1](https://corp.ticket-system.com/browse/$1)'
  }
}

[!WARNING]
Usages of \ in the json have to be escaped. E.g. \ becomes \\.

Custom placeholders

Starting with v3.2.0 the action provides a feature of defining CUSTOM_PLACEHOLDERS.

Custom placeholders allow to extract values from any existing placeholder and insert them into the target template.

Custom placeholders can be defined via the configuration.json as custom_placeholders. See the below example json:

{
  "template": "**Epics**\n#{{EPIC[*]}}\n\n#{{CHANGELOG}}",
  "pr_template": "- #{{TITLE}} - #{{URL}} #{{EPIC}}",
  "custom_placeholders": [
    {
      "name": "EPIC",
      "source": "BODY",
      "transformer": {
        "pattern": "[\\S\\s]*?(https:\\/\\/corp\\.atlassian\\.net\\/browse\\/EPIC-.{2,4})[\\S\\s]*",
        "target": "- $1"
      }
    }
  ]
}

This example will look for JIRA tickets in the EPIC project, and extract all of these tickets. The exciting part for that case is, that the ticket is PR-bound but can be used in the global TEMPLATE, but equally also in the PR template. This is unique for CUSTOM PLACEHOLDERS as standard placeholders do not offer this functionality.

A placeholder with the name as CUSTOM_PLACEHOLDER can be used as #{{CUSTOM_PLACEHOLDER}} in the target template. By default the same restriction applies as for PR vs. template placeholder. E.g. a global placeholder can only be used in the global template (and not in the PR template).

Custom placeholders offer one new feature, though. PR-related placeholders can be used in the global template via the following syntax:

• CUSTOM_PLACEHOLDER[*] - Will join all found values and insert them at the given location in the global template
• CUSTOM_PLACEHOLDER[0] / CUSTOM_PLACEHOLDER[index] - Will insert the first found value (item at index) into the global template

Gitea support 🧪

Starting with v4.1.0 the action is also compatible with gitea.

[!WARNING]
The API from gitea does not allow to retrieve the diff via its API, requiring the repo to be checked out

The API for gitea is equal to the one from GitHub, however it requires the platform to be specified.

- name: Build Changelog
  uses: https://github.com/mikepenz/release-changelog-builder-action@v5
  with:
    platform: "gitea" # gitea or GitHub, default is GitHub
    configuration: "configuration.json"
  env:
    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
$ npm test

It's suggested to export the token to your path before running the tests so that API calls can be done to GitHub.

export GITHUB_TOKEN=your_personal_github_pat

Local Testing 🧪

This GitHub action is fully developed in Typescript and can be run locally via npm or right from the browser using GitHub Codespace.

Doing so is a great way to test the action and/or your custom configurations locally, without the need to push and re-run GitHub actions over and over again.

To run locally, or to access private repositories (GitHub Codespaces has automatic access to public repos with the default token), you will require to provide a valid GITHUB_TOKEN with read-only permissions to access the repositories you want to run this action towards. (See more details in Token Permission)

To test your own configuration and use-case, the project contains a __tests__/demo/demo.test.ts file, modify this one to your needs. (e.g., change repo, change token, change settings, ...), and then run it via:

npm test -- demo.test.ts

One major benefit of setting up a custom test is that it will allow you to use JavaScripts full debugging support, including the option of breakpoints via (for example) Visual Code.

From GitHub codespaces, open the terminal panel -> Click the small arrow down beside + and pick JavaScript Debug Terminal (make sure to export the token again). Now execute the test with this terminal. (This is very similar to local Visual Code environments).

To run the common tests of the action, you require to export a valid GitHub token.

# Export the token in the CLI you use to execute.
export GITHUB_TOKEN=your_read_only_github_token

Afterwards it is possible to run any test included in the project:

npm test -- main.test.ts # modify the file name to run other testcases

Token Permission

Permissions depend on the specific use-case, however this action only requires read-only permissions as it will not make modifications to the repository.

GitHub actions

Depending on the given environment it may be required to define teh token scope for GitHub actions to read for contents and pull-requests.

permissions:
  contents: read
  pull-requests: read

GitHub Actions token scope.

Fine-grained personal access tokens

For Fine-grained personal access tokens this means:

• read for Pull requests
  • Covered by the pull-requests scope
• read for Commits
  • Covered by the contents scope
• read for Tags (if not available the from and to refs have to be provided)
  • Covered by the contents scope
• read to list reviews
  • Covered by the contents scope

Classic tokens

For Classic tokens you only have to create the token without special permissions.

Developed By

• Mike Penz
• mikepenz.com - mikepenz@gmail.com
• paypal.me/mikepenz

Credits

• Core parts of the PR fetching logic are based on pull-release-notes
  • Nikolay Blagoev - GitHub
• action-gh-release for a few great README ideas

Other actions

• xray-action
• action-junit-report
• jira-release-composition-action

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

All patches and changes applied to the original source are licensed under the Apache 2.0 license.

Copyright 2024 Mike Penz

Licensed 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.0

Unless required by applicable law or agreed to in writing, software
distributed 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 and
limitations under the License.

Sample result release notes / changelog