:octocat:๐Ÿ“„๐Ÿ”–๐Ÿ“ฆ

release-changelog-builder-action

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


-------

What's included ๐Ÿš€ • Setup ๐Ÿ› ๏ธ • Full Sample ๐Ÿ–ฅ๏ธ • Customization ๐Ÿ–๏ธ • Contribute ๐Ÿงฌ • License ๐Ÿ““

------- ### What's included ๐Ÿš€ - Super simple integration - ...even on huge repositories with hundreds of tags - Parallel releases support - 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: ```yml - name: "Build Changelog" id: build_changelog uses: mikepenz/release-changelog-builder-action@{latest-release} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` By default the action will try to automatically retrieve the `tag` from the current commit and automtacally resolve the `tag` before. Read more about this here. ### 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 referenceing the output by referencing it via the steps id. For example `build_changelog`. ```yml # ${{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 ```yml name: 'CI' on: push: tags: - '*' release: if: startsWith(github.ref, 'refs/tags/') runs-on: ubuntu-latest steps: - name: Build Changelog id: github_release uses: mikepenz/release-changelog-builder-action@main env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Create Release uses: actions/create-release@v1 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. ```yml - name: "Build Changelog" uses: mikepenz/release-changelog-builder-action@{latest-release} with: configuration: "configuration.json" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` This configuration is a `.json` file in the following format. ```json { "categories": [ { "title": "## ๐Ÿš€ Features", "labels": ["feature"] }, { "title": "## ๐Ÿ› Fixes", "labels": ["fix"] }, { "title": "## ๐Ÿงช Tests", "labels": ["test"] } ], "sort": "ASC", "template": "${{CHANGELOG}}\n\n
\nUncategorized\n\n${{UNCATEGORIZED}}\n
", "pr_template": "- ${{TITLE}}\n - PR: #${{NUMBER}}", "empty_template": "- no changes", "transformers": [ { "pattern": "[\\-\\*] (\\[(...|TEST|CI|SKIP)\\])( )?(.+?)\n(.+?[\\-\\*] )(.+)", "target": "- $4\n - $6" } ], "max_tags_to_fetch": 200, "max_pull_requests": 200, "max_back_track_time_days": 90, "exclude_merge_branches": [ "Owner/qa" ] } ``` Any section of the configuration can be ommited to have defaults apply. Defaults for the configuration can be found in the [configuration.ts](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/src/configuration.ts) Please see the [Configuration Specification](#configuration-specification) for detailed descriptions on the offered configuration options. ### Advanced workflow specification For advanced usecases additional settings can be provided to the action ```yml - 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 }} ``` ๐Ÿ’ก 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 | | 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 | ๐Ÿ’ก `${{ secrets.GITHUB_TOKEN }}` only grants rights to the current repository, for other repos please use a PAT (Personal Access Token). ### PR Template placeholders Table of supported placeholders allowed to be used in the `template` configuration. | **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 `pr_template` configuration. | **Placeholder** | **Description** | |----------------------|-------------------------------------------------------------------------------------------------| | `${{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 | ### Configuration Specification Table of descriptions for the `configuration.json` options. | **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 label against. If any PR label, matches any category label, the pull request will show up under this category | | sort | The sort order of pull requests. [ASC, DESC] | | template | Specifies the global template to pick for creating the changelog. See [Template placeholders](#template-placeholders) for possible values | | pr_template | Defines the per pull request template. See [PR Template placeholders](#pr-template-placeholders) for possible values | | empty_template | Template to pick if no changes are detected. Does not support placeholders | | transformers | An array of `transform` specification, 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 | ## Contribute ๐Ÿงฌ ```bash # 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. ```bash export GITHUB_TOKEN=your_personal_github_pat ``` ## Developed By * Mike Penz * [mikepenz.com](http://mikepenz.com) - * [paypal.me/mikepenz](http://paypal.me/mikepenz) ## Credits Core parts of the PR fetching logic are based on [pull-release-notes](https://github.com/nblagoev/pull-release-notes) - Nikolay Blagoev - [GitHub](https://github.com/nblagoev/) ## 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, 2020. ## Fork License All patches and changes applied to the original source are licensed under the Apache 2.0 license. Copyright 2020 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.