Skip to content

GitHub Action to generate changelog from conventional commits

License

Notifications You must be signed in to change notification settings

requarks/changelog-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Changelog from Conventional Commits - Github Action

This GitHub Action automatically generates a changelog based on all the Conventional Commits between the latest tag and the previous tag, or beween 2 specific tags.

Features

  • Generates the CHANGELOG changes in Markdown format
  • Turns PR ids into links and add the PR author.
  • Prepends a shortened commit SHA ID to the commit for quick access.
  • BREAKING CHANGE notes are added to the top of the changelog version along with the related commit.
  • Exports changelog to a variable that can used in a subsequent step to create a release changelog.
  • Automatically injects the changes into the CHANGELOG.md file or creates it if it doesn't exist yet. (optional)
  • Will not mess up with any header or instructions you already have at the top of your CHANGELOG.md.
  • Will not add duplicate version changes if it already exists in the CHANGELOG.md file.
  • Optionally exclude types from the CHANGELOG. (default: build,docs,other,style)

Example Workflows

Using the latest tag

name: Deploy

on:
  push:
    tags:
      - v[0-9]+.[0-9]+.[0-9]+

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Update CHANGELOG
        id: changelog
        uses: requarks/changelog-action@v1
        with:
          token: ${{ github.token }}
          tag: ${{ github.ref_name }}

      - name: Create Release
        uses: ncipollo/release-action@v1.12.0
        with:
          allowUpdates: true
          draft: false
          makeLatest: true
          name: ${{ github.ref_name }}
          body: ${{ steps.changelog.outputs.changes }}
          token: ${{ github.token }}

      - name: Commit CHANGELOG.md
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          branch: main
          commit_message: 'docs: update CHANGELOG.md for ${{ github.ref_name }} [skip ci]'
          file_pattern: CHANGELOG.md

Using a specific tag range

name: Deploy

on:
  push:
    tags:
      - v[0-9]+.[0-9]+.[0-9]+

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Get previous tag
        id: previousTag
        run: |
          name=$(git --no-pager tag --sort=creatordate --merged ${{ github.ref_name }} | tail -2 | head -1)
          echo "previousTag: $name"
          echo "previousTag=$name" >> $GITHUB_ENV

      - name: Update CHANGELOG
        id: changelog
        uses: requarks/changelog-action@v1
        with:
          token: ${{ github.token }}
          fromTag: ${{ github.ref_name }}
          toTag: ${{ env.previousTag }}
          writeToFile: false

      - name: Create Release
        uses: ncipollo/release-action@v1.12.0
        with:
          allowUpdates: true
          draft: true
          makeLatest: true
          name: ${{ github.ref_name }}
          body: ${{ steps.changelog.outputs.changes }}
          token: ${{ secrets.GITHUB_TOKEN }}

Inputs

Field Description Required Default
token Your GitHub token (e.g. ${{ github.token }})
tag The latest tag which triggered the job. (e.g. ${{ github.ref_name }})
(unless using fromTag and toTag)
fromTag The tag from which the changelog is to be determined (latest)
(unless using tag)
toTag The tag up to which the changelog is to be determined (oldest)
(unless using tag)
excludeTypes A comma-separated list of commit types you want to exclude from the changelog (e.g. doc,chore,perf) build,docs,other,style
excludeScopes A comma-separated list of commit scopes you want to include in the changelog (e.g. dev,release)
restrictToTypes A comma-separated list of commit types you want to restrict to for the changelog (e.g. feat,fix,refactor). Overrides excludeTypes if defined.
writeToFile Should CHANGELOG.md be updated with latest changelog true
changelogFilePath The CHANGELOG.md file path when writeToFile is true CHANGELOG.md
includeRefIssues Should the changelog include the issues referenced for each PR. true
useGitmojis Should type headers be prepended with their related gitmoji true
includeInvalidCommits Whether to include commits that don't respect the Conventional Commits format false
reverseOrder List commits in reverse order (from newer to older) instead of the default (older to newer). false

Outputs

Field Description
changes Generated CHANGELOG changes for the latest tag, without the version / date header (for use in GitHub Releases).

⚠️ Important ⚠️

You must already have 2 tags in your repository (1 previous tag + the current latest tag triggering the job). The job will exit with an error if it can't find the previous tag!