Generate Changelog from 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. References like #123 or @rhysd are automatically linked.

For example, CHANGELOG.md was generated from the releases page.

Other real-world examples:

• https://github.com/rhysd/actionlint/blob/main/CHANGELOG.md
• https://github.com/rhysd/hgrep/blob/main/CHANGELOG.md
• https://github.com/rhysd/git-brws/blob/master/CHANGELOG.md

Installation

Download binary from the releases page or build from sources with Go toolchain (1.22 or later).

$ go install github.com/rhysd/changelog-from-release/v3@latest

Usage

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

For more command line usage, see the -help output.

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 }}

FAQ

How can I update changelog before adding the release tag?

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.

1. Click 'Draft a new release' button in releases page and write up release note for the next release
2. Click 'Choose a tag' drop down and enter a tag name for the release which is not created yet. Then click '+ Create new tag: ... on publish' item in the drop down.
3. Save the draft by clicking 'Save draft'
4. Run changelog-from-release with setting a personal access token to $GITHUB_TOKEN environment variable
5. Commit the generated changelog
6. Create and push the new Git tag. Ensure the tag name is the same as one entered at 2.
7. Go to the draft release page created at 1. and publish the release by clicking 'Publish release' button

Setting 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.

How can I insert some templates at top/bottom of generated changelog?

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 header.

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.

How can I ignore some release tags?

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

How can I extract some release tags?

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

How can I ignore draft releases?

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

How can I get a changelog in a format other than Markdown?

changelog-from-release only supports Markdown. However you can convert the Markdown document into other formats such as plain text or HTML.

Most famous tool for this is Pandoc. For example, the following command converts the changelog file from Markdown into plain text.

pandoc CHANGELOG.md -t plain -o CHANGELOG.txt --wrap=none

Reference auto linking

GitHub automatically links to references to resources.

changelog-from-release provides the same auto-linking feature. It automatically links the following references and URLs in release notes.

Issue reference

#123 → [#123](https://github.com/owner/repo/issues/123)

External reference with GH- prefix is also supported.

GH-123 → [#123](https://github.com/owner/repo/issues/123)

User reference

@rhysd → [@rhysd](https://github.com/rhysd)

Commit reference

93e1af6ec49d23397baba466fba1e89cc8b6de39 → [`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec49d23397baba466fba1e89cc8b6de39)

Note

To avoid false-positives, only full-length (40 characters) commit hashes are converted.

Custom autolink

JIRA-123 → [JIRA-123](https://jira.my-company.com/browse/PROJ-123)

Note

Custom autolinks are configured on your repository. The API to fetch the custom autolinks configuration requires "Administration" repository permissions (read). When the permission lacks, changelog-from-release ignores the custom autolinks. You need to set your personal access token to the GITHUB_TOKEN environment variable.

Issue URL

https://github.com/owner/repo/issues/123 → [#123](https://github.com/owner/repo/issues/123)

For outside repositories,

https://github.com/other/repo/issues/123 → [other/repo#123](https://github.com/owner/repo/issues/123)

And URL to an issue comment is supported.

https://github.com/owner/repo/issues/123#issue-1212591132 → [#123 (comment)](https://github.com/owner/repo/issues/123#issue-1212591132)

Pull request URL

https://github.com/owner/repo/pull/123 → [#123](https://github.com/owner/repo/pull/123)

For outside repositories,

https://github.com/other/repo/pull/123 → [other/repo#123](https://github.com/owner/repo/pull/123)

And URL to a review comment is supported.

https://github.com/owner/repo/pull/123#pullrequestreview-1212591132 → [#123 (review)](https://github.com/owner/repo/pull/123#pullrequestreview-1212591132)

Commit URL

https://github.com/owner/repo/commit/93e1af6ec4 → [`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec4)

For outside repositories,

https://github.com/other/repo/commit/93e1af6ec4 → [other/repo`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec4)

Environment variables

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

Bug report or feature request

Please create an issue on GitHub. If something went wrong, it is helpful to include the debug log in the description. Debug log can be captured with the following command.

changelog-from-release -debug 2>log.txt

License

the MIT License