github_changelog_generator: a Ruby gem that writes your CHANGELOG.md from GitHub history

Installing the gem and running the first generation

This is a Ruby gem, so installation is the standard one, and the README points at rubylang.org for getting Ruby itself in place first.

$ gem install github_changelog_generator

The generated command line takes a namespace and a project name, where the namespace is likely your username if you own the project but can also be the namespace of a project you are documenting:

github_changelog_generator -u github_project_namespace -p github_project

What comes out is a `CHANGELOG.md` in Markdown. The README shows the shape of the output in a way that explains the whole design: a heading per version with a link to the tag and a link to the compare view, then separate lists for implemented enhancements, fixed bugs and merged pull requests, each entry linking back to its issue or pull request and crediting the author. The generator groups by label rather than guessing at categories from commit text.

The README also documents a concrete second example, generating the changelog for the ActionSheetPicker-3.0 project with the namespace set to github-changelog-generator. That is the shape of the command you would copy, replacing both arguments for your own project.

Docker as a way to skip the Ruby install

If you would rather not install Ruby or the gem on your machine, the README offers Docker as the alternative path, with a single example invocation:

$ docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator

The volume mount matters more than it looks. It puts your current working directory inside the container at `/usr/local/src/your-app`, which is how the generated file ends up on your host filesystem rather than disappearing when the container exits. The `--rm` flag is there so you do not accumulate stopped containers every time you cut a release.

For a team that already runs containers in CI, this is the more honest integration path than installing a gem on a build agent. The trade-off is that you are pulling a published image rather than pinning a gem version, so the version of the generator you run is controlled by the image tag rather than by your Gemfile. Neither route is documented in a lockstep pinning scheme, so if reproducibility matters to your release process you have to decide that yourself.

Rate limits decide whether you need a token

The README states the constraint that matters more than any feature: GitHub allows only 50 unauthenticated requests per hour. On a repository with a few thousand issues and pull requests, a full generation makes far more than 50 calls, so an unauthenticated run will hit the limit partway through. This is the single most likely reason a first attempt produces a partial file.

The fix is authentication, and the README gives two ways. You can pass the token on the command line, or set the `CHANGELOG_GITHUB_TOKEN` environment variable to your 40 digit token. The second is the better habit, because a token on a command line ends up in shell history and in any CI log that echoes the command. It links to the token generation page and notes that you only need the `repo` scope for private repositories, which is a genuinely minimal permission for a tool that reads your repository.

The environment variable route also has an advantage for CI: you can set it as a secret in the runner and never write the token into the repository at all. The README suggests adding the export to a shell profile or a `.env` file, which is fine for a workstation and wrong for a shared machine.

Labels and the params file as the real configuration

Everything the generator classifies, it classifies by label. That is the design decision that determines how useful the output is, and it also means the quality of your changelog is a property of your label hygiene rather than of the gem. Issues tagged as enhancements land under implemented enhancements, issues tagged as bugs land under fixed bugs, and merged pull requests get their own section with author attribution.

Defaults can be overridden by dropping a file named `.github_changelog_generator` in the project root, which the README shows with three keys:

unreleased=false
future-release=5.0.0
since-tag=1.0.0

Those three lines cover the cases that come up most. Turning off unreleased entries keeps work that has not shipped out of the file. Naming a future release lets you build a section for a version you have not cut yet. Setting a starting tag regenerates the history from a baseline instead of from the beginning of the repository, which is the setting to reach for when adopting the tool on a project that already has years of history.

The README points at its wiki page on advanced changelog generation examples for anything beyond this, and offers `--help` for the full option list:

$ github_changelog_generator --help

GitHub Enterprise needs two flags, not one

For GitHub Enterprise repositories the README is explicit that you must specify both the site and the API options, since an Enterprise install serves the API from a different path than github.com:

$ github_changelog_generator --github-site="https://github.yoursite.com" \
                             --github-api="https://github.yoursite.com/api/v3/"

Passing only one of them is the failure mode here, and it fails in a confusing way because the default still points at github.com. The `/api/v3/` suffix on the API URL is the part people miss.

There is also a mention in the README's feature list of an output mode that reports where the token came from, added in the v1.17.0 release, which suggests the maintainers were aware that token handling in this tool produces confusing failures on enterprise installs. When the API path is wrong you get an empty file rather than an error message pointing at the URL.

A long dormancy, then two releases five days apart

The release history is the most interesting thing in the repository. v1.16.4 was published on 2021-06-03 and handled named markdown links and direct rate-limit handling. Then nothing for nearly five years. v1.17.0 arrived on 2026-03-13 and v1.18.0 on 2026-03-18, five days later, and the last push to the repository was on 2026-03-18. So treat the current line as young and the earlier history as a long pause, not as a steady cadence.

What v1.17.0 changed is mostly compatibility work: support for Ruby 4.0, an update to Ruby 3.2.2, raising the lowest supported Ruby version to 3.0, and removal of the `multi_json` gem dependency. It also fixed SSL certificate errors, updated the RuboCop config, and fixed a case where a single commit was processed more than once. v1.18.0 is a bug-fix release: a race condition, a wrong tag lookup, branch memoization and nil sections, plus closed issues about `undefined method 'map' for nil:NilClass` in branch handling.

Those error messages are the honest description of this gem's failure history. Branches returning nil, tags resolving to the wrong ref, commits counted twice. The style of fixes suggests the tool leans on the GitHub API in ways that break when the API returns less than expected, which is worth keeping in mind before wiring it into a release you cannot afford to redo.

The repository layout backs this up. Beyond `lib/`, `bin/` and `spec/`, there is a `man/` directory for man pages, a `.rubocop.yml` with a `.rubocop_todo.rb` companion file, `.overcommit.yml` and `.hound.yml` for commit hooks, `.codeclimate.yml` for static analysis, and `SECURITY.md`. The README's table of contents also lists sections covering a summary block, a Rake task for migrating from a manually maintained changelog, an alternatives comparison, and creating GitHub release notes from the generated file.

Editorial conclusion

This gem earns its place in a repository that already labels its issues carefully, because the grouping work it does is exactly the part people abandon by hand. It will not write your release notes prose, it will not tell you which change matters, and it reads the GitHub API rather than your git history, so a project with a strong commit-message convention gets less out of it. Start by running the CLI once against your own repository with a token, check the labels section before you wire it into a Rake task, and read the generated output against your own `CHANGELOG.md`.

Frequently asked questions

Official sources

1. github-changelog-generator/github-changelog-generator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases