Documentation

• What's included 🚀
• Setup
  • Configure the workflow
  • Action outputs
• Full Sample 🖥️
• Customization 🖍️
  • Note
  • Configuration
  • Advanced workflow specification
  • PR Template placeholders
  • Template placeholders
  • Configuration Specification
• Experimental 🧪
• Contribute 🧬
• Local Testing 🧪
• Developed By
• Credits
• Other actions
• License
• Fork License
• Sample result release notes / changelog

release-changelog-builder-action

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

What's included 🚀 • Setup 🛠️ • Sample 🖥️ • Customization 🖍️ • Contribute 🧬 • Local Testing 🧪 • License 📓

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

#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.

#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 release on GitHub - specifying body with constructed changelog

Note: Pre v4 PRs will only show up in the changelog if assigned one of the default label categories "feature", "fix" or "test". Starting with v4 these PRs will be in the Uncategorized section.

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

#Customization 🖍️

#Note

Warning: 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 2 options:

1. When checking out the source via git (E.g.: actions/checkout), the action will use the first commit.
2. Create a 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. 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 configuration options to modify vast areas of its behavior. To do so, provide the configuration file to the workflow using the configuration setting.

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

Note Defaults for the configuration can be found in the configuration.ts

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

This 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 appropiate.)

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

#Advanced workflow specification

For advanced use cases 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).

#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.

#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.

#Configuration Specification

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

#Experimental 🧪

Starting with v3.2.0 the action provides an experimental 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"
      }
    }
  ]
}

#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. 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 this action locally, first make sure you provide a GITHUB_TOKEN with enough permissions to access the repository.

# GitHub token for the action
export GITHUB_TOKEN=your_read_only_github_token

Afterwards run the testcases with:

npm test -- custom.test.ts

import {resolveConfiguration} from '../src/utils'
import {ReleaseNotesBuilder} from '../src/releaseNotesBuilder'
 
jest.setTimeout(180000)
 
it('Test custom changelog builder', async () => {
  const configuration = resolveConfiguration(
    '',
    'configs_test/configuration_approvers.json'
  )
  const releaseNotesBuilder = new ReleaseNotesBuilder(
    null, // baseUrl
    null, // token
    '.',  // repoPath
    'mikepenz',                                         // user
    'release-changelog-builder-action-playground',      // repo
    '1.5.0',         // fromTag
    '2.0.0',         // toTag
    true,   // includeOpen
    false, // failOnError
    false, // ignorePrePrelease
    true,  // enable to fetch reviewers
    false, // enable to fetch release information
    false, // enable to fetch reviews
    false, // commitMode
    configuration  // configuration
  )
 
  const changeLog = await releaseNotesBuilder.build()
  console.log(changeLog)
  expect(changeLog).toStrictEqual(``)
})

Additionally it is possible to do full debugging including the option of breakpoints via (for example) Visual Code. Open the project in Visual code -> open the terminal -> use the + and start a new JavaScript Debug Terminal. Afterwards run the tests as described above.

#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, 2021.

#Fork License

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

Copyright 2022 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