Awesome Open Source
Awesome Open Source
๐Ÿ“„๐Ÿ”–๐Ÿ“ฆ

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 ๐Ÿงฌ โ€ข 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/[email protected]{latest-release}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_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.

Output Description
outputs.changelog The built release changelog built from the merged pull requests
outputs.owner Specifies the owner of the repository processed
outputs.repo Describes the repository name, which was processed
outputs.fromTag Defines the fromTag which describes the lower bound to process pull requests for
outputs.toTag Defines the toTag which describes the upper bound to process pull request for
outputs.failed Defines if there was an issue with the action run, and the changelog may not have been generated correctly. [true, false]

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: PRs will only show up in the changelog if assigned one of the default label categories "feature", "fix" or "test"

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/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release
        uses: actions/[email protected]
        with:
          tag_name: ${{ github.ref }}
          release_name: ${{ github.ref }}
          body: ${{steps.github_release.outputs.changelog}}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Customization ๐Ÿ–๏ธ

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/[email protected]{latest-release}
  with:
    configuration: "configuration.json"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

โš ๏ธ Please note: It is required to have a checkout step prior to the changelog step, to allow the action to discover the configuration file.

โš ๏ธ When running this action for a non tags trigger the toTag can't be automatically resolved, as such it is either required to provide toTag directly, or to specify a different fetch-depth: with the checkout action to include tags.

๐Ÿ’ก By default not specifying fromTag or toTag will resolve toTag from either the ref or alternatively fallback to the latest tag from git. fromTag is resolved by sorting tags using semver. Check the configuration for alternatives.

This configuration is a .json file in the following format.

{
    "categories": [
      {
        "title": "## ๐Ÿš€ Features",
        "labels": ["feature"]
      },
      {
        "title": "## ๐Ÿ› Fixes",
        "labels": ["fix"]
      },
      {
        "title": "## ๐Ÿงช Tests",
        "labels": ["test"]
      }
    ],
    "ignore_labels": [
      "ignore"
    ],
    "sort": "ASC",
    "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": "(.) (.+)",
        "target": "$1",
        "on_property": "title"
      }
    ],
    "transformers": [
      {
        "pattern": "[\\-\\*] (\\[(...|TEST|CI|SKIP)\\])( )?(.+?)\n(.+?[\\-\\*] )(.+)",
        "target": "- $4\n  - $6"
      }
    ],
    "max_tags_to_fetch": 200,
    "max_pull_requests": 200,
    "max_back_track_time_days": 365,
    "exclude_merge_branches": [
      "Owner/qa"
    ],
    "tag_resolver": {
      "method": "semver"
    },
    "base_branches": [
      "dev"
    ]
}

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

๐Ÿ’ก ignore_labels take precedence over category labels, allowing to specifically exclude certain PRs.

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

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/[email protected]{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 }}

๐Ÿ’ก All input values are optional. It is only required to provide the token either via the input, or as env variable.

Input Description
configuration Relative path, to the configuration.json file, providing additional configurations
outputFile Optional relative path to a file to store the resulting changelog in.
owner The owner of the repository to generate the changelog for
repo Name of the repository we want to process
fromTag Defines the 'start' from where the changelog will consider merged pull requests
toTag Defines until which tag the changelog will consider merged pull requests
path Allows to specify an alternative sub directory, to use as base
token Alternative config to specify token. You should prefer env.GITHUB_TOKEN instead though
ignorePreReleases Allows to ignore pre-releases for changelog generation (E.g. for 1.0.1... 1.0.0-rc02 <- ignore, 1.0.0 <- pick). Only used if fromTag was not specified. Default: false
failOnError Defines if the action will result in a build failure if problems occurred. Default: false
commitMode Special configuration for projects which work without PRs. Uses commit messages as changelog. This mode looses access to information only available for PRs. Default: false

๐Ÿ’ก ${{ 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.

Placeholder Description
${{NUMBER}} The number referencing this pull request. E.g. 13
${{TITLE}} Specified title of the merged pull request
${{URL}} Url linking to the pull request on GitHub
${{MERGED_AT}} The ISO time, the pull request was merged at
${{AUTHOR}} Author creating and opening the pull request
${{LABELS}} The labels associated with this pull request, joined by ,
${{MILESTONE}} Milestone this PR was part of, as assigned on GitHub
${{BODY}} Description/Body of the pull request as specified on GitHub
${{ASSIGNEES}} Login names of assigned GitHub users, joined by ,
${{REVIEWERS}} GitHub Login names of specified reviewers, joined by ,

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.

Placeholder Description Empty
${{CHANGELOG}} The contents of the changelog, matching the labels as specified in the categories configuration
${{UNCATEGORIZED}} All pull requests not matching a specified label in categories
${{IGNORED}} All pull requests defining labels matching the ignore_labels configuration
${{OWNER}} Describes the owner of the repository the changelog was generated for x
${{REPO}} The repository name of the repo the changelog was generated for x
${{FROM_TAG}} Defines the 'start' from where the changelog did consider merged pull requests x
${{TO_TAG}} Defines until which tag the changelog did consider merged pull requests x
${{CATEGORIZED_COUNT}} The count of PRs which were categorized
${{UNCATEGORIZED_COUNT}} The count of PRs and changes which were not categorized. No label overlapping with category labels
${{IGNORED_COUNT}} The count of PRs and changes which were specifically ignored from the changelog.

Configuration Specification

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

Input Description
categories An array of category specifications, offering a flexible way to group changes into categories
category.title The display name of a category in the changelog
category.labels An array of labels, to match pull request labels against. If any PR label matches any category label, the pull request will show up under this category
ignore_labels An array of labels, to match pull request labels against. If any PR label overlaps, the pull request will be ignored from the changelog. This takes precedence over category labels
sort The sort order of pull requests. [ASC, DESC]
template Specifies the global template to pick for creating the changelog. See Template placeholders for possible values
pr_template Defines the per pull request template. See PR Template placeholders for possible values
empty_template Template to pick if no changes are detected. See Template placeholders for possible values
label_extractor An array of transform specifications, offering a flexible API to extract additinal labels from a PR (Default: body, Default in commit mode: commit message).
label_extractor.pattern A regex pattern, extracting values of the change message.
label_extractor.target The result pattern. The result text will be used as label. If empty, no label is created.
label_extractor.on_property The property to retrieve the text from. This is optional. Defaults to: body. Alternative values: title, author, milestone.
label_extractor.flags Defines the regex flags specified for the pattern. Default: gu
transformers An array of transform specifications, offering a flexible API to modify the text per pull request. This is applied on the change text created with pr_template. transformers are executed per change, in the order specified
transformer.pattern A regex pattern, extracting values of the change message.
transformer.target The result pattern, the regex groups will be filled into. Allows for full transformation of a pull request message. Including potentially specified texts
max_tags_to_fetch The maximum amount of tags to load from the API to find the previous tag. Loaded paginated with 100 per page
max_pull_requests The maximum amount of pull requests to load from the API. Loaded paginated with 30 per page
max_back_track_time_days Defines the max amount of days to go back in time per changelog
exclude_merge_branches An array of branches to be ignored from processing as merge commits
tag_resolver Section to provide configuration for the tag resolving logic. Used if no fromTag is provided
tag_resolver.method Defines the method to use. Current options are: semver, sort. Default: semver
base_branches The target branches for the merged PR, ingnores PRs with different target branch. Values can be a regex. Default: allow all base branches

Contribute ๐Ÿงฌ

# Install the dependencies
$ npm install

# 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

# Verify lint is happy
$ npm run lint -- --fix

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

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

Fork License

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

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


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
typescript (12,070)ย 
automation (738)ย 
workflow (349)ย 
github-actions (261)ย 
ci (247)ย 
actions (120)ย 
cd (63)ย 
release (60)ย 
action (58)ย 
changelog (51)ย 
pull-requests (49)ย 
release-automation (33)ย 
issues (32)ย 
labels (27)ย