git-cliff action ⛰️

This action generates a changelog based on your Git history using git-cliff on the fly!

Usage

Input variables

• version: git-cliff version to use. (e.g. "latest", "v2.13.1")
• config: Path of the configuration file. (Default: "cliff.toml")
• args: Arguments to pass to git-cliff. (Default: "-v")
• github_token: The GitHub API token used to download git-cliff and to authenticate git-cliff's GitHub integration (e.g. extracting usernames, contributors, PR links) to avoid rate limits. Requires a classic or fine-grained token without permissions.

Note

GitHub API token order of precedence is as follows:

1. Input variable (github_token)
2. Environment variable (GITHUB_TOKEN)
3. GitHub context (default) (${{ github.token }})

Output variables

• changelog: Output file that contains the generated changelog.
• content: Content of the changelog.
• version: Version of the latest release.

Environment variables

• OUTPUT: Output file. (Default: "git-cliff/CHANGELOG.md")
• DEBUG: Set to a not empty value (e.g. "true") to print executed commmands. (Default: unset)

Important

Check out the entire history via fetch-depth: 0 before running this action.

- name: Checkout
  uses: actions/checkout@v6
  with:
    fetch-depth: 0

Otherwise, you might end up getting empty changelogs or git ref errors depending on arguments passed to git-cliff.

Running the action outside of GitHub

If you run the action in Gitea or GitHub Enterprise, the github_token input is invalid. You have two options:

• Pass an empty value (github_token: "") (limit of 60 requests per hour per IP address).
• Create a GitHub token and pass it through GitHub secrets to avoid rate limiting.

Examples

Simple

The following example fetches the whole Git history (fetch-depth: 0), generates a changelog in ./CHANGELOG.md, and prints it out.

jobs:
  changelog:
    name: Generate changelog
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Generate a changelog
        uses: orhun/git-cliff-action@v4
        id: git-cliff
        with:
          config: cliff.toml
          args: --verbose
        env:
          OUTPUT: CHANGELOG.md

      - name: Print the changelog
        run: cat "${{ steps.git-cliff.outputs.changelog }}"

Advanced

The following example generates a changelog for the latest pushed tag and sets it as the body of the release.

It uses svenstaro/upload-release-action for uploading the release assets.

jobs:
  changelog:
    name: Generate changelog
    runs-on: ubuntu-latest
    outputs:
      release_body: ${{ steps.git-cliff.outputs.content }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Generate a changelog
        uses: orhun/git-cliff-action@v4
        id: git-cliff
        with:
          config: cliff.toml
          args: -vv --latest --strip header
        env:
          OUTPUT: CHANGES.md
          GITHUB_REPO: ${{ github.repository }}

      # use release body in the same job
      - name: Upload the binary releases
        uses: svenstaro/upload-release-action@v2
        with:
          file: binary_release.zip
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref }}
          body: ${{ steps.git-cliff.outputs.content }}

  # use release body in another job
  upload:
    name: Upload the release
    needs: changelog
    runs-on: ubuntu-latest
    steps:
      - name: Upload the binary releases
        uses: svenstaro/upload-release-action@v2
        with:
          file: binary_release.zip
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref }}
          body: ${{ needs.changelog.outputs.release_body }}

Committing the changelog

You can use this action as follows if you want to generate a changelog and commit it to the repository:

jobs:
  changelog:
    name: Generate changelog
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Generate changelog
        uses: orhun/git-cliff-action@v4
        with:
          config: cliff.toml
          args: --verbose
        env:
          OUTPUT: CHANGELOG.md
          GITHUB_REPO: ${{ github.repository }}

      - name: Commit
        run: |
          git checkout <branch>
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          set +e
          git add CHANGELOG.md
          git commit -m "Update changelog"
          git push https://${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}.git <branch>

Please note that you need to change the <branch> to the branch name that you want to push.

Run arbitrary git-cliff commands

If you want more flexibility, you can install git-cliff via taiki-e/install-action and then run any git-cliff commands.

For example, you can use the command git-cliff --bumped-version to determine the next release version:

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Install git-cliff
        uses: taiki-e/install-action@git-cliff

      - name: Determine release version
        run: |
          release_version=$(git-cliff --bumped-version)
          echo "Next release version is $release_version"

License

Licensed under either of Apache License Version 2.0 or The MIT License at your option.

Copyright

Copyright © 2021-2024, Orhun Parmaksız