What is Changelog CI?
Changelog CI is a GitHub Action that enables a project to automatically generate changelogs.
Changelog CI can be triggered on pull_request, workflow_dispatch and any other events that can provide the required inputs. Learn more about events that trigger workflows
The workflow can be configured to perform any (or all) of the following actions:
-
For
pull_requestevent:- Generates changelog using Pull Request Titles or Commit Messages made after the last release.
- Prepends the generated changelog to the
CHANGELOG.md/CHANGELOG.rstfile. - Then Commits the modified
CHANGELOG.md/CHANGELOG.rstfile to the release pull request branch. - Adds a Comment on the release pull request with the generated changelog.
-
For other events:
- Generate changelog using Pull Request Title or Commit Messages made after the last release.
- Prepends the generated changelog to the
CHANGELOG.md/CHANGELOG.rstfile. - Then Creates a Pull Request with the
CHANGELOG.md/CHANGELOG.rstfile changes.
How Does It Work:
Changelog CI uses python and GitHub API to generate changelog for a repository. First, it tries to get the latest release from the repository (If available). Then, it checks all the pull requests / commits merged after the last release using the GitHub API. After that, it parses the data and generates the changelog. It is able to use Markdown or reStructuredText to generate Changelog. Finally, It writes the generated changelog at the beginning of the CHANGELOG.md/CHANGELOG.rst (or user-provided filename) file. In addition to that, if a user provides a configuration file (JSON/YAML), Changelog CI parses the user-provided configuration file and renders the changelog according to users configuration. Then, if the workflow run was triggered by a pull_request event, the changes are committed and/or commented to the release Pull request, otherwise a new Pull Request is created with the changes.
Usage:
-
To use this Action on a
pull_requestevent, The pull request title must match with the defaultpull_request_title_regexor the user-providedpull_request_title_regexfrom the config file. -
To use this Action on any other events, You must provide
release_versionas an input to the workflow. It can be provided usingworkflow_dispatcheventsinputoption or from any other sources.
Basic Integration (for pull_request event): To integrate Changelog CI on your repositories, Put .github/workflows/changelog-ci.yml file in your repository with the following content:
name: Changelog CI
on:
pull_request:
types: [ opened ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- name: Run Changelog CI
uses: saadmk11/[email protected]
Workflow input options
These are the inputs that can be provided on the workflow.
| Name | Required | Description | Default |
|---|---|---|---|
changelog_filename |
No | Name of the changelog file (Any file name with .md or .rst extension) |
CHANGELOG.md |
config_file |
No | User configuration file path (configuration file can be in JSON or YAML format) |
null |
committer_username |
No | Name of the user who will commit the changes to GitHub | github-actions[bot] |
committer_email |
No | Email Address of the user who will commit the changes to GitHub | github-actions[bot]@users.noreply.github.com |
release_version |
No (Required if workflow run is not triggered by a pull_request event) |
The release version that will be used on the generated Changelog | null |
github_token |
No | GITHUB_TOKEN provided by the workflow run or Personal Access Token (PAT) |
github.token |
Workflow with All Options:
name: Changelog CI
on:
pull_request:
types: [ opened ]
# Optionally you can use `workflow_dispatch` to run Changelog CI Manually
workflow_dispatch:
inputs:
release_version:
description: 'Set Release Version'
required: true
jobs:
build:
runs-on: ubuntu-latest
steps:
# Checks-out your repository
- uses: actions/[email protected]
- name: Run Changelog CI
uses: saadmk11/[email protected]
with:
# Optional, you can provide any name for your changelog file,
# We currently support Markdown (.md) and reStructuredText (.rst) files
# defaults to `CHANGELOG.md` if not provided.
changelog_filename: CHANGELOG.rst
# Optional, only required when you want more customization
# e.g: group your changelog by labels with custom titles,
# different version prefix, pull request title and version number regex etc.
# config file can be in JSON or YAML format.
config_file: changelog-ci-config.json
# Optional, This will be used to configure git
# defaults to `github-actions[bot]` if not provided.
committer_username: 'test'
committer_email: '[email protected]'
# Optional, only required when you want to run Changelog CI
# on an event other than `pull_request` event.
# In this example `release_version` is fetched from `workflow_dispatch` events input.
# You can use any other method to fetch the release version
# such as environment variable or from output of another action
release_version: ${{ github.event.inputs.release_version }}
# Optional
github_token: ${{ secrets.GITHUB_TOKEN }}
Note: To Enable Commenting, Disable Committing, Group Changelog Items, Use Commit Messages and some other options, see Configuration to learn more.
Changelog CI Badge:
Output:
Configuration
Using an optional configuration file
Changelog CI is will run perfectly fine without including a configuration file. If a user seeks to modify the default behaviors of Changelog CI, they can do so by adding a JSON or YAML config file to the project. For example:
-
Including
JSONfilechangelog-ci-config.json:with: config_file: changelog-ci-config.json
-
Including
YAMLfilechangelog-ci-config.yaml:with: config_file: changelog-ci-config.yaml
Configuration File options
These are the options that can be provided on the config_file.
| Name | Required | Description | Default | Options |
|---|---|---|---|---|
changelog_type |
No | pull_request option will generate changelog using pull request title. commit_message option will generate changelog using commit messages. |
pull_request |
pull_request or commit_message |
header_prefix |
No | The prefix before the version number. e.g. version: in Version: 1.0.2 |
Version: |
|
commit_changelog |
No | If it's set to true then Changelog CI will commit the changes to the release pull request. (A pull Request will be created with the changes if the workflow run is not triggered by a pull_request event) |
true |
true or false |
comment_changelog |
No | If it's set to true then Changelog CI will comment the generated changelog on the release pull request. (Only applicable for workflow runs triggered by a pull_request event) |
false |
true or false |
pull_request_title_regex |
No | If the pull request title matches with this regex Changelog CI will generate changelog for it. Otherwise, it will skip the changelog generation. (Only applicable for workflow runs triggered by a pull_request event) |
^(?i:release) |
|
version_regex |
No | This regex is used to find the version name/number (e.g. 1.0.2, v2.0.2) from the pull request title. in case of no match, changelog generation will be skipped. (Only applicable for workflow runs triggered by a pull_request event) |
SemVer |
|
group_config |
No | By adding this you can group changelog items by your repository labels with custom titles. | null |
|
include_unlabeled_changes |
No | if set to false the generated changelog will not contain the Pull Requests that are unlabeled or the labels are not on the group_config option. This option will only be used if the group_config option is added and the changelog_type option is set to pull_request. |
true |
true or false |
unlabeled_group_title |
No | This option will set the title of the unlabeled changes. This option will only be used if the include_unlabeled_changes option is set to true, group_config option is added and the changelog_type option is set to pull_request. |
Other Changes |
Example Configuration File
Written in JSON:
{
"changelog_type": "commit_message",
"header_prefix": "Version:",
"commit_changelog": true,
"comment_changelog": true,
"include_unlabeled_changes": true,
"unlabeled_group_title": "Unlabeled Changes",
"pull_request_title_regex": "^Release",
"version_regex": "v?([0-9]{1,2})+[.]+([0-9]{1,2})+[.]+([0-9]{1,2})\\s\\(\\d{1,2}-\\d{1,2}-\\d{4}\\)",
"group_config": [
{
"title": "Bug Fixes",
"labels": ["bug", "bugfix"]
},
{
"title": "Code Improvements",
"labels": ["improvements", "enhancement"]
},
{
"title": "New Features",
"labels": ["feature"]
},
{
"title": "Documentation Updates",
"labels": ["docs", "documentation", "doc"]
}
]
}
Written in YAML:
changelog_type: 'commit_message' # or 'pull_request'
header_prefix: 'Version:'
commit_changelog: true
comment_changelog: true
include_unlabeled_changes: true
unlabeled_group_title: 'Unlabeled Changes'
pull_request_title_regex: '^Release'
version_regex: 'v?([0-9]{1,2})+[.]+([0-9]{1,2})+[.]+([0-9]{1,2})\s\(\d{1,2}-\d{1,2}-\d{4}\)'
group_config:
- title: Bug Fixes
labels:
- bug
- bugfix
- title: Code Improvements
labels:
- improvements
- enhancement
- title: New Features
labels:
- feature
- title: Documentation Updates
labels:
- docs
- documentation
- doc
-
In this Example
version_regexmatches any version number including date ( e.g:v1.1.0 (01-23-2018)) in the pull request title. If you don't provide anyregexChangelog CI will use defaultSemVerpattern. e.g.1.0.1,v1.0.2. -
Here the changelog will be generated using commit messages because of
changelog_type: 'commit_message'. -
Here
pull_request_title_regexwill match any pull request title that starts withReleaseyou can match Any Pull Request Title by adding thispull_request_title_regex": ".*",
See this example output with group_config
See this example output without group_config
Changelog CI in Action (Comment & Commit)
Example Changelog Output using config file (Pull Request):
Version: v2.1.0 (02-25-2020)
Bug Fixes
New Features
- #68: Update README.md
Documentation Updates
- #66: Docs update
Version: v1.1.0 (01-01-2020)
Bug Fixes
Documentation Updates
- #66: Docs update
Example Changelog Output using config file (Commit Messages):
Version: v2.1.0 (02-25-2020)
- 123456: Keep updating the readme
- 123456: Again updating the Same Readme file
- 123456: Update README.md
- 123456: Docs update
Version: v1.1.0 (01-01-2020)
Example Changelog Output without using config file:
Version: 0.0.2
Version: 0.0.1
- #43: It feels like testing never ends
- #35: Testing again and again
- #44: This is again another test, getting tired
- #37: This is again another test
License
The code in this project is released under the MIT License.
2 Dec 20, 2021
149 Dec 08, 2022
395 Jan 04, 2023
22k Jan 08, 2023
5 Jul 10, 2022
1 Jan 15, 2022
0 Jan 31, 2022
1.3k Jan 02, 2023
6 Dec 25, 2022
1 Dec 20, 2021
2.4k Dec 24, 2022
3 Nov 05, 2021
7 Mar 31, 2022
152 Dec 25, 2022
3 May 01, 2022
28.2k Jan 08, 2023
10 Oct 22, 2022
8 Nov 26, 2022
4 Jan 12, 2022
23 Apr 04, 2022