Create Changelog

This action creates an initial Changelog from the commit history.

This is usually the included in your workflow after building and testing your library with CMake Workflow in another job with the complete matrix.

The commits considered go from the latest commit up to a commit containing a version commit pattern specified by version-pattern.

The result can be used as the initial body for an automated release, a CHANGELOG.md file, or a job summary.

Each commit is parsed as a loose variant of a conventional commit in the following format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The body and footer are always ignored.
If no type is indicated, the description goes to an initial "other" category in the message.
If no scope is indicated, the description goes to an initial "general" scope in the type messages.
Breaking changes are indicated.

This action uses the local commit history to generate the notes. Ensure the fetch-depth option is set when cloning your repository in CI. If this option is unset, the checkout action will perform a shallow clone and the Changelog will only include the latest commit.

- uses: actions/checkout@v3
  with:
    fetch-depth: 100

This parameter can also be used as a limit on the number of commits the action should consider.

Standalone CLI

This action can also be used as a standalone command-line tool to generate changelogs locally, outside of GitHub Actions workflows. This is useful for:

Previewing changelog output before creating a release
Generating changelogs for local development
Integrating changelog generation into custom scripts

Installation

# Clone the repository
git clone https://github.com/alandefreitas/cpp-actions.git
cd cpp-actions/create-changelog

# Install dependencies and build
npm install
npm run build

Global Installation

To install create-changelog as a global command accessible from any directory:

# From the repository root, build dependencies first
npm install
npm run prepare

# Then link the create-changelog package globally
cd create-changelog
npm link

After linking, you can run create-changelog from any git repository:

# Navigate to any project and generate its changelog
cd /path/to/any/project
create-changelog

# Or with options
create-changelog -o RELEASE_NOTES.md --limit 50

To uninstall the global command:

npm unlink -g create-changelog

Global installation is useful for testing changelog generation locally before committing workflow changes, or for generating changelogs in projects that don’t use this action.

Usage

# Run from the create-changelog directory
npm run create-changelog -- --source_dir /path/to/your/repo

# Or run the compiled script directly
node lib/create-changelog.js --source_dir /path/to/your/repo

CLI Options

All action inputs are available as CLI options with underscores instead of hyphens (e.g., --source_dir, --version_pattern). Use -o as shorthand for --output_path.

Example

# Generate changelog for current directory
node lib/create-changelog.js

# Generate changelog with custom output path
node lib/create-changelog.js -o RELEASE_NOTES.md

# Generate changelog for a specific repository
node lib/create-changelog.js --source_dir ~/projects/my-repo --limit 50

Example

steps:
- name: Changelog
  uses: alandefreitas/cpp-actions/create-changelog@v1.9.1
  with:
    output-path: CHANGELOG.md
    thank-non-regular: ${{ startsWith(github.ref, 'refs/tags/') }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    link-commits: ${{ github.ref_name == 'develop' }}

Input Parameters

Parameter

Description

Default

source-dir

The source directory from whose commits will be analyzed.

.

version-pattern

A regex pattern used to identify if a commit is a version delimiter.

When a commit has a message that matches this pattern, the list of commits considered in the notes is complete.

For instance, assuming the pattern '(Bump|Set)\s+version', when we find a commit subject such as 'Bump version to 1.0.0', the list of commits considered in the notes is complete.

This constraint does not apply to the current and latest commit.

(Bump|Set)\s+version

tag-pattern

A regex pattern used to identify if a commit is a tagged delimiter.

When a commit has the same hash has the commit associated with a tag whose name matches this pattern, the list of commits considered in the notes is complete.

For instance, assuming the pattern 'v.\..\..*', when we find a commit with the same hash as the commit associated with the tag 'v1.0.0', the list of commits considered in the notes is complete.

This tag is then associated as the parent version of the current release, and this information is included at the end of the changelog.

This constraint does not apply to the current and latest commit.

v.\..\..*

output-path

The path where the changelog will be stored.

Relative paths are resolved from the source directory.

CHANGELOG.md

limit

The limit on the number of commits considered in the Changelog.

If the limit is set to 0 or undefined, all commits are considered.

0

thank-non-regular

Thank non-regular contributors.

The action will attempt to identify non-regular contributors by analyzing the commit history and the GitHub token provided.

Non-regular contributors are contributors that do not have a are not part of the repository’s collaborators and have a small number of commits.

The changelog will include a thank you message to these contributors, including a tag to their GitHub profile.

When the Changelog is used in a release, this tag will usually be used by GitHub to notify these contributors of the new release with their contribution and the thank you message.

true

check-unconventional

Check for commits that do not follow the conventional commit format.

This input controls the behavior when unconventional commits are detected:

- false: Disable checking (no warnings or errors) - warn or true: Emit warnings for unconventional commits (default) - error: Fail the action if unconventional commits are found

When enabled, if one of the new commits in a PR does not follow the conventional commit format, the action will either warn or fail depending on this setting.

This helps ensure all commit messages can be used in the changelog so that it’s consistent and that the release notes are clear and concise.

warn

link-commits

Link commit ids in the changelog to the repository commit.

For instance, if the changelog includes a commit id such as '471aec5', instead of including "#471aec5" next to the commit message, it will include the full version with the link:

#471aec5

This is usually unnecessary because GitHub flavored markdown automatically links commits id in text to the commits in the same repository. Thus, including explicit links would often make the output more verbose and remove any extra GitHub functionality, such as pop ups associated with these ids.

However, when the outputs is only going to be used as an action summary or in any other context outside GitHub, these automatic links do not exist and it’s often a good idea to explicitly include them to allow the reader to navigate to these repository commits.

false

github-token

Github token to identify information about the project.

This is currently used to:

- Fetch the commit history to compare with the proposed changes and create a full changelog including the changes proposed in a PR and the changes that are already in the main branch. - Fetch the list of collaborators to identify non-regular contributors.

The reason we need to fetch the commit history is because the checkout action only fetches the latest commit so the information about existing commits is not readily available to the workflow.

The value for this token is usually set as the value of secrets.GITHUB_TOKEN.

Although the action does not require this token to work, it will be limited in the number of requests it can make to the GitHub API and might be forced to work with limited information.

update-summary

When set to true, this action will update the workflow summary with the current changelog.

true

trace-commands

Trace commands executed by the workflow.

false

include-types

Comma-separated list of commit types to include in the changelog.

When specified, only commits with these types will appear in the changelog. If empty (default), all commit types are included before applying exclusions.

Common types: feat, fix, perf, refactor, docs, style, build, test, ci, chore, release, other

Example: 'feat, fix, perf, docs'

Note: The 'other' type represents commits that don’t follow conventional commit format.

exclude-types

Comma-separated list of commit types to exclude from the changelog.

Commits with these types will be filtered out from the changelog output. This filter is applied after include-types (if specified).

Common types: feat, fix, perf, refactor, docs, style, build, test, ci, chore, release, other

Example: 'chore, style, release'

Tip: Use this to create cleaner changelogs by excluding routine maintenance commits.

chore, style

sort-by

Specifies how commits should be sorted within each scope in the changelog.

Available options: - most-changes-first: Sort by lines changed, most changes first (default) - latest-first: Sort by date, newest commits first - oldest-first: Sort by date, oldest commits first

Note: When using most-changes-first, the action will fetch diff statistics for each commit, which may take additional time for repositories with many commits.

Example: Sort by newest commits first: yaml - uses: alandefreitas/cpp-actions/create-changelog@v1 with: sort-by: 'latest-first'.

most-changes-first