GitHub Action
git-cliff - Changelog Generator
git-cliff action ⛰️
This action generates a changelog based on your Git history using git-cliff on the fly!
version
:git-cliff
version to use. (e.g."latest"
,"v2.7.0"
)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 getgit-cliff
release information via the GitHub API to avoid rate limits. (Default:${{ github.token }}
)
changelog
: Output file that contains the generated changelog.content
: Content of the changelog.version
: Version of the latest release.
OUTPUT
: Output file. (Default:"git-cliff/CHANGELOG.md"
)
Important
Check out the entire history via fetch-depth: 0
before running this action.
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
Otherwise, you might end up getting empty changelogs or git ref
errors depending on arguments passed to git-cliff
.
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.
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@v4
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 }}"
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@v4
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 }}
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@v4
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.
Licensed under either of Apache License Version 2.0 or The MIT License at your option.
Copyright © 2021-2024, Orhun Parmaksız