gitchangelog creates a changelog from git log history using multiple template engines and a config file. Output can be either reStructuredText or MarkDown, with the latter format as default for this action (mainly for generating GitHub release pages).

What you can do with gitchangelog-action:

• generate a nicely-formatted/configurable github release document to use with something like softprops/action-gh-release
• generate a full changelog during any workflow (capture as a workflow or release artifact)
• use a custom gitchangelog.rc file from your source repo

By default this action will use the same gitchangelog.rc.github.release config file installed by the gitchangelog package. The full option list is shown below.

The canonical dogfood example is the release.yml and corresponding github release page in the gitchangelog repo.

To enable the default release page changes file, create a .yml file under .github/workflows with the following contents.

name: gitchangelog
on: [push]

jobs:
  release:
    name: gitchangelog-action
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: gitchangelog action step
        uses: sarnold/gitchangelog-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN}}

The above is enough to generate the default release output, but should be paired with a release action to populate the github release page (as shown below). The action will try its best to figure out the current and previous tags, however, if you set the VERSION variable it will be used for the current tag in the change diff.

name: gitchangelog
on:
  push:
    # trigger a release on any tag push
    tags:
      - '*'

jobs:
  build:
    # build stuff here to create release artifacts if needed

  release:
    name: gitchangelog with gh-release action
    runs-on: ubuntu-latest
    steps:
      - name: Get version
        id: get_version
        run: |
          echo "VERSION=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV
          echo ${{ VERSION }}

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

      - name: Generate changes file
        uses: sarnold/gitchangelog-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN}}

      - name: Create release
        uses: softprops/action-gh-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ env.VERSION }}
          name: Release ${{ env.VERSION }}
          body_path: CHANGES.md
          draft: true
          prerelease: false

github_token:	GITHUB_TOKEN secret (automatically provided by Github)
config_file:	Path to gitchangelog.rc (default: Markdown release cfg)
output_file:	Filename for changelog (default: CHANGES.md)
extra_sort:	Additionally sort the list of found tags (default: False)
no_args:	Pass no ref args to gitchangelog (always generate full changelog)

The following options are not yet implemented:

commit_changelog:	Whether to commit the changelog file (default: false)
target_branch:	Branch that the action will target (default: current branch)

• If you need to generate changelogs outside the github release context, the workaround for now is using actions/upload-artifact.

Please refer to the gitchangelog readme document for further details.

This action runs in a Docker container and requires the Ubuntu CI runner. In your workflow job configuration, you should set the runs-on property to ubuntu-latest:

jobs:
  release:
    runs-on: ubuntu-latest

The gitchangelog tool itself is built and tested in github CI using Linux, Macos, and Windows, so you can always generate output on your local machine as needed.