release-changelog-builder-action

release-changelog-builder-action

... a GitHub action that builds your release notes / changelog fast, simple and exactly the way you want.

Quickstart 🛠️ • Configuration • Placeholders • Sample 🖥️ • Reference 📖 • License 📓

Quickstart 🛠️

1. Build the changelog for the tag that triggered the workflow:

- name: Build Changelog
  id: build_changelog
  uses: mikepenz/release-changelog-builder-action@v6
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2. Use the result as the body of the release:

- name: Create Release
  uses: mikepenz/action-gh-release@v3
  with:
    body: ${{ steps.build_changelog.outputs.changelog }}

3. Shape the output by declaring your own categories — see Configuration:

  with:
    configurationJson: |
      {
        "template": "#{{CHANGELOG}}",
        "categories": [
          { "title": "## 🚀 Features", "labels": ["feature"] },
          { "title": "## 🐛 Fixes", "labels": ["fix", "bug"] }
        ]
      }

Reference

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@v6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: mikepenz/[email protected] #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@v6
        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"],
                    "collapsed": true
                }
              ]
            }
        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@v6
        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]*)",
                  "on_property": "title",
                  "target": "$1"
                }
              ]
            }
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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 }}

- name: "App1 Changelog"
  id: build_app1_changelog
  if: startsWith(github.ref, 'refs/tags/')
  uses: mikepenz/release-changelog-builder-action@{latest-release}
  with:
    includeOnlyPaths: |
      app1/
      shared/
    fromTag: "v1.0.0"
    toTag: "v2.0.0"
    token: ${{ secrets.GITHUB_TOKEN }}

[!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@v6
  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"

[!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.

Commit Template placeholders

Table of supported placeholders allowed to be used in the commit_template configuration, which will be included in the release notes / changelog. Applies to HYBRID and COMMIT modes only.

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.

[XYZ-1234] This is my PR title

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

{
  "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.

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

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。