Automatic Changelog generator

• Usage
• Inputs
  • Preferred API
  • Github Token
  • Commit Types
  • Default Commit Type
  • Release Name
  • Monorepo Detectors
  • Include Root Commits
  • Release Name Prefix
  • Mention Authors
  • Mention New Contributors
  • Include GitHub Compare Link
  • SemVer Compatibility
  • Use GitHub Autolink
• Outputs
  • Changelog
  • Pre-release
  • Release ID
  • Package Name
  • Package Path
• Example Usage

To use this action, your commit messages have to follow the format below:

type(category): description [flag]

• The type must be one of commit-types input keys. In the changelog output, the value will be used.

  The changelogs will be in the same order as commit-types input.

  If the type doesn't match any of the provided commit-types input keys, The default-commit-type input will be used instead.

• The category is optional and can be anything of your choice.

• The flag is optional (if provided, it must be surrounded in square brackets) and can be one of the followings:

  • ignore (Omits the commit from the changelog)

  If flag is not found in the list, it'll be ignored.

Commit messages not matching the format mentioned above will be ignored in the changelog output.

(Optional)

The preferred API to acquire the required information to generate the changelog.

Possible options:

• Git
• GitHub

Notes:

• Git: Uses the local git CLI to read commits and tags from the checked-out repository. This is optimized for large repositories by streaming commits and tags (it does not load full histories into memory). It can optionally use GitHub (if a token is available) to resolve GitHub usernames from author emails.
• GitHub: Uses GitHub APIs for commits/tags and for generating GitHub-style release notes sections (e.g. New Contributors).

Default:

GitHub

(Optional)

Github token.

Notes:

• Required when using preferred-api: GitHub.
• When using preferred-api: Git, a token is only needed for optional enrichment (e.g. trying to resolve GitHub usernames from author emails). If omitted, Git mode will fall back to non-@username formatting where necessary.

Default:

${{ github.token }}

(Optional)

Commit types.

The default value is based on the Conventional Commits Specification

Default:

feat    : New Features
fix     : Bug Fixes
build   : Build System & Dependencies
perf    : Performance Improvements
docs    : Documentation
test    : Tests
refactor: Refactors
chore   : Chores
ci      : CI
style   : Code Style
revert  : Reverts

(Optional)

Default commit type.

This input will be used when the commit message matches none of the defined commit-types input.

Default:

Other Changes

(Optional)

Release name (version, e.g. v1.0.0).

For monorepo package releases, use package release tags in this format:

{name}@{version}

Examples:

web@1.2.3
api@2.0.0
@scope/ui@0.4.1

When release-name matches a detected workspace package tag, the action generates a package changelog.

Default:

${{ github.ref_name }}

(Optional)

Monorepo detection strategies used for package release tags.

Possible options:

• auto
• pnpm
• npm
• yarn
• lerna
• nx

Use comma-separated values to limit detection:

pnpm,nx

auto tries pnpm, npm/yarn workspaces, lerna, then nx.

Default:

auto

(Optional)

Controls root/shared commits in monorepo package changelogs. This input is ignored when release-name does not match a detected package tag.

Possible options:

• false: only include commits touching the selected package path.
• auto: include selected package commits and related root workspace/config files.
• all: include selected package commits and any root/shared files, but still exclude commits that only touch sibling packages.

Default:

false

(Optional)

Release name (version) prefix.

Example: For a release name such as @actions/github/v1.0.0 it would be @actions/github/

Default:

""

(Optional)

Mention the author of each commit.

Default:

true

(Optional)

Mention new contributors at the bottom of the changelog (New Contributors).

Default:

true

(Optional)

Include GitHub compare at the bottom of the changelog (Full Changelog).

If there is no previous tag determined it'll be ommited regardless of the provided value.

Default:

true

(Optional)

Include GitHub pull request links at each log if applicable.

Default:

true

(Optional)

Include GitHub commit links at each log.

Default:

true

(Optional)

Enable Semver-based version comparison.

If enabled it'll determine whether the GitHub ref is a valid semver string, it'll fail the action in case it's not.

It'll then determine whether the version is a pre-release or not, if it is, the previous version will be selected from any version (pre-release or not) lesser than the current ref, if current ref is not a pre-release, the previous version will be selected only from the latest version (not pre-release) lesser than the current ref.

Default:

true

(Optional)

Use GitHub Autolink.

Default:

true

The generated changelog.

Indicates whether it's a pre-release or not.

if semver is set to true, otherwise this output will always return false.

The pre-release id in case of pre-release being true, latest otherwise. (e.g. alpha, beta, rc, canary)

if semver is set to true, otherwise this output will always return latest.

The selected monorepo package name when a package release tag is detected, otherwise an empty string.

The selected monorepo package path when a package release tag is detected, otherwise an empty string.

Using with default inputs:

- name: Changelog
  uses: ardalanamini/auto-changelog@v4
  id  : changelog

Using with custom inputs:

- uses: ardalanamini/auto-changelog@v4
  id  : changelog
  name: Changelog
  with:
    github-token            : ${{ github.token }}
    preferred-api           : GitHub
    commit-types            : |
      feat    : New Features
      fix     : Bug Fixes
      build   : Build System & Dependencies
      perf    : Performance Improvements
      docs    : Documentation
      test    : Tests
      refactor: Refactors
      chore   : Chores
      ci      : CI
      style   : Code Style
      revert  : Reverts
    default-commit-type     : Other Changes
    release-name            : v1.0.0
    monorepo-detectors      : auto
    include-root-commits    : false
    release-name-prefix     : ""
    mention-authors         : true
    mention-new-contributors: true
    include-compare-link    : true
    include-pr-links        : true
    include-commit-links    : true
    semver                  : true
    use-github-autolink     : true

Using with a monorepo package release:

- uses: ardalanamini/auto-changelog@v4
  id  : changelog
  name: Changelog
  with:
    release-name        : web@1.2.3
    monorepo-detectors  : pnpm,nx
    include-root-commits: auto