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_request event:

  • Generates changelog using Pull Request Titles or Commit Messages made after the last release.
  • Prepends the generated changelog to the CHANGELOG.md/CHANGELOG.rst file.
  • Then Commits the modified CHANGELOG.md/CHANGELOG.rst file 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.rst file.
  • Then Creates a Pull Request with the CHANGELOG.md/CHANGELOG.rst file 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_request event, The pull request title must match with the default pull_request_title_regex or the user-provided pull_request_title_regex from the config file.

• To use this Action on any other events, You must provide release_version as an input to the workflow. It can be provided using workflow_dispatch events input option 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/checkout@v2

      - name: Run Changelog CI
        uses: saadmk11/changelog-ci@v1.1.2

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/checkout@v2

      - name: Run Changelog CI
        uses: saadmk11/changelog-ci@v1.1.2
        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: 'test@test.com'
          # 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:

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

Workflow Output:

The workflow outputs the changelog as a GitHub Action Output. The name of the output is changelog. The output can be used in other steps of the action. For example:

- name: changelog-ci
  uses: saadmk11/changelog-ci@v1.1.2
  id: changelog-ci

- name: Get Changelog Output
  run: |
    echo "${{ steps.changelog-ci.outputs.changelog }}"
    echo "${{ steps.changelog-ci.outputs.changelog }}" >> $GITHUB_STEP_SUMMARY

Here the output is used to write the generated changelog to the GitHub Actions Job Summary.

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 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.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
exclude_labels	No	If the pull Request includes one of the labels in this option the changelog for that pull request will be ignored.	null

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}\\)",
  "exclude_labels": ["bot", "dependabot", "ci"],
  "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}\)'
exclude_labels:
  - bot
  - dependabot
  - ci
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 provide any regex Changelog CI will use default SemVer 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 that starts with Release you can match Any Pull Request Title by adding this pull_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

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