What is Changelog CI?

Changelog CI is a GitHub Action that enables a project to utilize anautomatically generated changelog.

The workflow can be configured to perform any (or all) of the following actions

• Generate changelog using Pull Request or Commit Messages.

• Prepend the generated changelog to the CHANGELOG.md file and then Commit modified CHANGELOG.md file to the release pull request.

• Add a Comment on the release pull request with the generated changelog.

How Does It Work:

Changelog CI uses python and GitHub API to generate changelog for arepository. First, it tries to get the latest release from the repository (Ifavailable). Then, it checks all the pull requests / commits merged after the last releaseusing the GitHub API. After that, it parses the data and generatesthe changelog. Finally, It writes the generated changelog at the beginning ofthe CHANGELOG.md (or user-provided filename) file. In addition to that, if auser provides a config (JSON/YAML file), Changelog CI parses the user-provided configfile and renders the changelog according to users config. Then the changesare committed and/or commented to the release Pull request.

Usage:

To use this Action The pull request title must match with thedefault regexor the user-provided regex from the config file.

Default Title Regex: ^(?i:release) (title must start with the word "release" (case-insensitive))

Default Changelog Type: pull_request (Changelog will be generated using pull request title),You can generate changelog using commit_message as wellUsing an optional configuration file.

Default Version Number Regex: This Regex will be checked against a PullRequest title. This follows SemVer (Semantic Versioning) pattern. e.g. 1.0.0, 1.0, v1.0.1 etc.

For more details on Semantic Versioning pattern go to thislink: https://regex101.com/r/Ly7O1x/3/

Note: You can use a custom regular expression to parse your changelog addingone to the optional configuration file. To learn more, seeUsing an optional configuration file.

To Enable Commenting, Disable Committing, Group Changelog Items, Use Commit Messages andsome other options, see Configuration to learn more.

To integrate Changelog CI with your repositories Actions, Put this step insideyour .github/workflows/workflow.yml file:

- name: Run Changelog CI
    uses: saadmk11/changelog-ci@v0.8.0
    with:
      # Optional, you can provide any name for your changelog file,
      # defaults to `CHANGELOG.md` if not provided.
      changelog_filename: MY_CHANGELOG.md
      # 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: 'test@test.com'
    env:
      # optional, only required for `private` repositories
      # and required if the changelog comment
      # option is turned on through the config file
      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Changelog CI Badge:

![Changelog CI Status](https://github.com/<username>/<repository>/workflows/Changelog%20CI/badge.svg)

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 soby adding a JSON or YAML config file to the project. For example:

• Including JSON file changelog-ci-config.json:

  with:
    config_file: changelog-ci-config.json

• Including YAML file changelog-ci-config.yaml:

  with:
    config_file: changelog-ci-config.yml

Valid options

• changelog_typeYou can use pull_request (Default) or commit_message as the value for this option.pull_request option will generate changelog using pull request title.commit_message option will generate changelog using commit messages.

• header_prefixThe prefix before the version number. e.g. version: in Version: 1.0.2

• commit_changelogValue can be true or false. if not provided defaults to true. If it isset to true then Changelog CI will commit to the release pull request.

• comment_changelogValue can be true or false. if not provided defaults to false. If it isset to true then Changelog CI will comment on the release pull request. Thisrequires GITHUB_TOKEN to be added to the workflow.

• pull_request_title_regexIf the pull request title matches with this regex Changelog CI will generatechangelog for it. Otherwise, it will skip the changelog generation.If pull_request_title_regex is not provided defaults to ^(?i:release),then the title must begin with the word "release" (case-insensitive).

• version_regexThis regex tries to find the version number from the pull request title. incase of no match, changelog generation will be skipped. if version_regex isnot provided, it defaults toSemVer pattern.

• group_configBy adding this you can group changelog items by your repository labels withcustom titles.

See this example output with group_config

See this example output without group_config

Example Config File

Written in JSON:

{
  "changelog_type": "commit_message",
  "header_prefix": "Version:",
  "commit_changelog": true,
  "comment_changelog": true,
  "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
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_regex matches any version number including date (e.g: v1.1.0 (01-23-2018)) in the pull request title. If you don't provideany regex Changelog CI will use defaultSemVer pattern. 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_regex will match any pull request title thatstarts with Releaseyou can match Any Pull Request Title by adding this pull_request_title_regex": ".*",

Click here to see the example output using this config

Example Workflow

name: Changelog CI

# Controls when the action will run. Triggers the workflow on a pull request
on:
  pull_request:
    types: [ opened, reopened ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Checks-out your repository
      - uses: actions/checkout@v2

      - name: Run Changelog CI
        uses: saadmk11/changelog-ci@v0.8.0
        with:
          changelog_filename: CHANGELOG.md
          config_file: changelog-ci-config.json
        # Add this if you are using it on a private repository
        # Or if you have turned on commenting through the config file.
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Changelog CI in Action (Comment & Commit)

Example Changelog Output using config file (Pull Request):

Version: v2.1.0 (02-25-2020)

Bug Fixes

• #53: Keep updating the readme
• #54: Again updating the Same Readme file

New Features

• #68: Update README.md

Documentation Updates

• #66: Docs update

Version: v1.1.0 (01-01-2020)

Bug Fixes

• #53: Keep updating the readme
• #54: Again updating the Same Readme file

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)

• 123456: Keep updating the readme
• 123456: Again updating the Same Readme file
• 123456: Docs update

Example Changelog Output without using config file:

Version: 0.0.2

• #53: Keep updating the readme
• #54: Again updating the Same Readme file
• #55: README update

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.