changelog-updater Action

A GitHub Action to update a changelog with the latest release notes.

The Action …

• adds a new second level heading for the new release
• pastes your release notes in the appropriate place in CHANGELOG.md

If your changelog follows the "Keep a Changelog" format and contains an "Unreleased"-heading, the Action will update the heading to point to the compare view between the latest version and HEAD. (Read more about this here)

Don't want to use GitHub Actions? Checkout the changelog-updater CLI that powers this Action. Want to learn more about this Action? Read my introduction blog post.

Usage

The Action is best used in a Workflow that listens to the release-event and the type released. This way, the name and body of your release will be added to the CHANGELOG.

The following is an example Workflow ready to be used.

The Workflow checks out the target branch of the release, updates the ./CHANGELOG.md-file with the name and the contents of the just released release and commits the changes back to your repository using git-auto-commit.

# .github/workflows/update-changelog.yaml
name: "Update Changelog"

on:
  release:
    types: [released]

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          ref: ${{ github.event.release.target_commitish }}

      - name: Update Changelog
        uses: stefanzweifel/changelog-updater-action@v1
        with:
          latest-version: ${{ github.event.release.tag_name }}
          release-notes: ${{ github.event.release.body }}

      - name: Commit updated CHANGELOG
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          branch: ${{ github.event.release.target_commitish }}
          commit_message: Update CHANGELOG
          file_pattern: CHANGELOG.md

To generate the release notes automatically for you, I can recommend using the release-drafter Action.

Advanced Usage

The following workflow is a bit more advanced. It …

• extracts the exact release date from the git tag
• uses the target branch of the release in the "Unreleased" compare URL
• pushes the created commit to the target branch of the commit

Show update-changelog.yaml

# .github/workflows/update-changelog.yaml
name: "Update Changelog"

on:
  release:
    types: [released]

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          # Fetch entire history of repository to ensure relase date can be
          # extracted from commit of the given tag.
          fetch-depth: 0
          # Checkout target branch of this release. Ensures that the CHANGELOG
          # is not out of date.
          ref: ${{ github.event.release.target_commitish }}

      - name: Extract release date from git tag
        id: release_date
        run: |
          echo "::set-output name=date::$(git log -1 --date=short --format=%ad '${{ github.event.release.tag_name }}')"

      - name: Update Changelog
        uses: stefanzweifel/changelog-updater-action@v1
        with:
          # Pass extracted release date, release notes and version to the Action.
          release-date: ${{ steps.release_date.outputs.date }}
          release-notes: ${{ github.event.release.body }}
          latest-version: ${{ github.event.release.tag_name }}
          compare-url-target-revision: ${{ github.event.release.target_commitish }}

      - name: Commit updated CHANGELOG
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          # Push updated CHANGELOG to release target branch.
          branch: ${{ github.event.release.target_commitish }}
          commit_message: Update CHANGELOG
          file_pattern: CHANGELOG.md

Inputs

Checkout action.yml for a full list of supported inputs.

Expected Changelog Formats

At minimum, the Action requires an empty CHANGELOG.md file to exist in your repository. When executed, the Action will place the release notes at the bottom of the document. If your changelog already contains a second level heading, the Action will put the release notes above previous release notes in the document.

Your changelog will look something like this:

# Changelog

## v1.1.0 - 2021-02-01

### Added

- New Feature A

## v1.0.0 - 2021-01-01

- Initial Release

If you want to learn more on how the Action determines the place for the release notes, read the the notes in the README of the CLI that powers this Action.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

We also provide major version tags to make it easier to always use the latest release of a major version. For example you can use stefanzweifel/changelog-updater-action@v1 to always use the latest release of the current major version. (More information about this here.)

Credits

• Stefan Zweifel
• All Contributors

License

This project is licensed under the MIT License - see the LICENSE file for details.