Simple changelog generator via GitHub releases
changelog-from-release
is a (too) small command line tool to generate changelog from
GitHub Releases. It fetches releases of the repository via GitHub API and generates
changelog in Markdown format.
For example, CHANGELOG.md was generated from the releases page.
Other real-world examples:
Download binary from the releases page or build from sources with Go toolchain.
$ go install github.com/rhysd/changelog-from-release/v3@latest
Running changelog-from-release
with no argument outputs a changelog text in Markdown format to
stdout. Please redirect the output to your changelog file.
$ cd /path/to/repo
$ changelog-from-release > CHANGELOG.md
$ cat CHANGELOG.md
Automation with GitHub Actions is also offered. Please read action's README for more details.
- uses: rhysd/changelog-from-release/action@v3
with:
file: CHANGELOG.md
github_token: ${{ secrets.GITHUB_TOKEN }}
For more usage, see -help
output.
References in a release note are automatically converted to links by changelog-from-release
.
#123
are converted to links to the issue pages@rhysd
are converted to links to the user profile pages93e1af6ec49d23397baba466fba1e89cc8b6de39
are converted to links to the
commit pages. To avoid false-positives, only full-length (40 characters) commit hashes are converted.For example,
Commit: 93e1af6ec49d23397baba466fba1e89cc8b6de39
Author: @rhysd
Issue: #123
is converted to
Commit: [`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec49d23397baba466fba1e89cc8b6de39)
Author: [@rhysd](https://github.com/rhysd)
Issue: [#123](https://github.com/owner/repo/issues/123)
For example, how to include changes for v1.2.3 in CHANGELOG.md
before creating a Git tag v1.2.3
?
Please use a release draft.
changelog-from-release
with setting a personal access token to $GITHUB_TOKEN
environment variableSetting a personal access token at 2. is mandatory since release drafts are private information. API token associated with your account is necessary to fetch it. If you use the action, an API token is automatically generated by GitHub Actions so you don't need to create a token by yourself.
Since changelog-from-release
command just generates changelog history, you can insert your
favorite templates before/after redirecting the generated output to CHANGELOG.md
file.
# Insert header
cat <<-EOS > CHANGELOG.md
Changelog
=========
This is a footer.
EOS
changelog-from-release -l 2 >> CHANGELOG.md
# Insert footer
cat <<-EOS >> CHANGELOG.md
This is a footer.
EOS
If your shell supports $()
, header and footer can be inserted once.
cat <<-EOS > CHANGELOG.md
Changelog
=========
This is a header.
$(changelog-from-release -l 2)
This is a footer.
EOS
-l 2
means using ##
instead of #
for each release section. Please adjust it for your use case.
If you're using the action, use header
and footer
inputs to insert texts
before/after the generated changelog.
- uses: rhysd/changelog-from-release/action@v3
with:
file: CHANGELOG.md
github_token: ${{ secrets.GITHUB_TOKEN }}
args: -l 2
header: |
Changelog
=========
This is header.
footer: |-
This is footer.
For example, if your project has nightly
tag release for nightly builds, it should be excluded from
changelog.
In this case, use -i
command line option to ignore some release tags by regular expression:
changelog-from-release -i '^nightly$' > CHANGELOG.md
For example, if your project uses v{major}.{minor}.{patch}
format for release tags, a changelog
should be created with extracting them.
In this case, use -e
command line option to extract some release tags by regular expression:
changelog-from-release -e '^v\d+\.\d+\.\d+$' > CHANGELOG.md
If you're using the GitHub Action and don't want draft releases to be included in the changelog, you
can use the -d
flag to omit them:
changelog-from-release -d=false > CHANGELOG.md
GITHUB_API_BASE_URL
For GitHub Enterprise, please set GITHUB_API_BASE_URL
environment variable to configure API
base URL.
export GITHUB_API_BASE_URL=https://github.your-company.com/api/v3/
GITHUB_TOKEN
If changelog-from-release
reported API rate limit exceeded or no permission to access the repository,
consider to specify a personal access token.
export GITHUB_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx