{"id":13405759,"url":"https://github.com/github-changelog-generator/github-changelog-generator","last_synced_at":"2026-03-13T05:04:12.858Z","repository":{"id":22675119,"uuid":"26018608","full_name":"github-changelog-generator/github-changelog-generator","owner":"github-changelog-generator","description":"Automatically generate change log from your tags, issues, labels and pull requests on GitHub.","archived":false,"fork":false,"pushed_at":"2024-11-26T07:32:04.000Z","size":2334,"stargazers_count":7449,"open_issues_count":150,"forks_count":848,"subscribers_count":108,"default_branch":"master","last_synced_at":"2025-05-05T17:32:39.053Z","etag":null,"topics":["changelog","changelog-generator","generator","github-api","github-extension","hacktoberfest","labels","markdown","notable-changes","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github-changelog-generator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["skywinder","olleolleolle"],"patreon":["skywinder","olleolleolle"],"open_collective":null,"ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2014-10-31T14:06:48.000Z","updated_at":"2025-05-04T05:23:10.000Z","dependencies_parsed_at":"2024-06-12T09:24:15.044Z","dependency_job_id":"3256de28-b8f6-43c9-a102-39cb0cd22d1c","html_url":"https://github.com/github-changelog-generator/github-changelog-generator","commit_stats":{"total_commits":1308,"total_committers":109,"mean_commits":12.0,"dds":0.4923547400611621,"last_synced_commit":"cdc661f9b91eb352b8d2aee09864df4d67938bf7"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github-changelog-generator%2Fgithub-changelog-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github-changelog-generator%2Fgithub-changelog-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github-changelog-generator%2Fgithub-changelog-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github-changelog-generator%2Fgithub-changelog-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github-changelog-generator","download_url":"https://codeload.github.com/github-changelog-generator/github-changelog-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252542575,"owners_count":21764992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changelog","changelog-generator","generator","github-api","github-extension","hacktoberfest","labels","markdown","notable-changes","ruby"],"created_at":"2024-07-30T19:02:10.693Z","updated_at":"2026-03-13T05:04:12.822Z","avatar_url":"https://github.com/github-changelog-generator.png","language":"Ruby","readme":"[![Gem Version](https://badge.fury.io/rb/github_changelog_generator.svg)](http://badge.fury.io/rb/github_changelog_generator)\n[![Ruby CI](https://github.com/github-changelog-generator/github-changelog-generator/actions/workflows/test.yml/badge.svg)](https://github.com/github-changelog-generator/github-changelog-generator/actions/workflows/test.yml)\n[![Join the chat at https://gitter.im/github-changelog-generator/chat](https://badges.gitter.im/github-changelog-generator/chat.svg)](https://gitter.im/github-changelog-generator/chat?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# github-changelog-generator ![GitHub Logo](../master/images/logo.jpg)\n\n\u003c!--\nTo update TOC, please run:\n\u003e doctoc ./README.md --github\n --\u003e\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n  - [Changelog generation has never been so easy](#changelog-generation-has-never-been-so-easy)\n  - [*What’s the point of a changelog?*](#whats-the-point-of-a-changelog)\n  - [*Why should I care?*](#why-should-i-care)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Running with CLI:](#running-with-cli)\n  - [Running with Docker](#running-with-docker)\n- [Output example](#output-example)\n  - [Params](#params)\n  - [Params File](#params-file)\n  - [GitHub token](#github-token)\n- [Migrating from a manual changelog](#migrating-from-a-manual-changelog)\n  - [Rake task](#rake-task)\n- [Features and advantages of this project](#features-and-advantages-of-this-project)\n  - [Using the summary section feature](#using-the-summary-section-feature)\n  - [Alternatives](#alternatives)\n  - [Projects using this library](#projects-using-this-library)\n- [Practical Use Cases](#practical-use-cases)\n  - [Creating GitHub Release Notes](#creating-github-release-notes)\n- [Am I missing some essential feature?](#am-i-missing-some-essential-feature)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [Contact us](#contact-us)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n### Changelog generation has never been so easy\n\n**Fully automated changelog generation** - This gem generates a changelog file based on **tags**, **issues** and merged **pull requests** (and splits them into separate lists according to labels) from :octocat: GitHub.\n\nSince you don't have to fill your `CHANGELOG.md` manually now: just run the script, relax and take a cup of :coffee: before your next release! :tada:\n\n### *What’s the point of a changelog?*\n\nTo make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.\n\n### *Why should I care?*\n\nBecause software tools are for _people_. \"Changelogs make it easier for users and\ncontributors to see precisely what notable changes have been made between each\nrelease (or version) of the project.\"\n\n:arrow_right: *[https://keepachangelog.com](https://keepachangelog.com)*\n\n## Installation\n\nGitHub Changelog Generator is a [Ruby](https://www.ruby-lang.org/)\nprogram, distributed as a RubyGem. The Ruby language homepage has an [Installation page](https://www.ruby-lang.org/en/documentation/installation/).\n\nInstall the gem like:\n\n    $ gem install github_changelog_generator\n\nDepending on your system, you _may_ need to run the shell as an Administrator (Windows),\nor use `sudo gem install github_changelog_generator` (Linux).\n\n\n## Usage\n\n\n### Running with CLI:\n\n\t   github_changelog_generator -u github_project_namespace -p github_project\n\n(where the project namespace is _likely_ your username if it's a project you own, but it could also be the namespace of the project)\n\n\n### Running with Docker\n\nUsing [Docker](https://www.docker.com/products/docker-desktop) is an alternative to installing Ruby and the gem.\n\nExample invocation:\n\n    $ docker run -it --rm -v \"$(pwd)\":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator\n\n\n\n- For GitHub Enterprise repos, specify *both* `--github-site` and `--github-api` options:\n\n       $ github_changelog_generator --github-site=\"https://github.yoursite.com\" \\\n                                  --github-api=\"https://github.yoursite.com/api/v3/\"\n\n\nThis generates a `CHANGELOG.md`, with pretty Markdown formatting.\n\n\n## Output example\n\n- Look at **[CHANGELOG.md](https://github.com/github-changelog-generator/github-changelog-generator/blob/master/CHANGELOG.md)** for this project\n- [ActionSheetPicker-3.0/CHANGELOG.md](https://github.com/skywinder/ActionSheetPicker-3.0/blob/develop/CHANGELOG.md) was generated by command:\n\n      $ github_changelog_generator -u github-changelog-generator -p ActionSheetPicker-3.0\n\n- In general, it looks like this:\n\n\u003e ## [1.2.5](https://github.com/github-changelog-generator/github-changelog-generator/tree/1.2.5) (2015-01-15)\n\u003e\n\u003e [Full Changelog](https://github.com/github-changelog-generator/github-changelog-generator/compare/1.2.4...1.2.5)\n\u003e\n\u003e **Implemented enhancements:**\n\u003e\n\u003e - Use milestone to specify in which version bug was fixed [\\#22](https://github.com/github-changelog-generator/github-changelog-generator/issues/22)\n\u003e\n\u003e **Fixed bugs:**\n\u003e\n\u003e - Error when trying to generate log for repo without tags [\\#32](https://github.com/github-changelog-generator/github-changelog-generator/issues/32)\n\u003e\n\u003e **Merged pull requests:**\n\u003e\n\u003e - PrettyPrint class is included using lowercase 'pp' [\\#43](https://github.com/github-changelog-generator/github-changelog-generator/pull/43) ([schwing](https://github.com/schwing))\n\u003e\n\u003e - support enterprise github via command line options [\\#42](https://github.com/github-changelog-generator/github-changelog-generator/pull/42) ([glenlovett](https://github.com/glenlovett))\n\n### Params\n\nPrint help for all command-line options to learn more details:\n\n    $ github_changelog_generator --help\n\nFor more details about params, read the Wiki page: [**Advanced changelog generation examples**](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Advanced-change-log-generation-examples)\n\n### Params File\n\nIn your project root, you can put a params file named `.github_changelog_generator` to override default params:\n\nExample:\n\n```\nunreleased=false\nfuture-release=5.0.0\nsince-tag=1.0.0\n```\n\n### GitHub token\n\nGitHub only allows **50 unauthenticated requests per hour**.\n\nTherefore, it's recommended to run this script with authentication by using a **token**.\n\nHere's how:\n\n- [Generate a token here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token) - you only need \"repo\" scope for private repositories\n- Either:\n    - Run the script with `--token \u003cyour-40-digit-token\u003e`; **OR**\n    - Set the `CHANGELOG_GITHUB_TOKEN` environment variable to your 40 digit token\n\nYou can set an environment variable by running the following command at the prompt, or by adding it to your shell profile (e.g., `.env`, `~/.bash_profile`, `~/.zshrc`, etc):\n\n    export CHANGELOG_GITHUB_TOKEN=\"«your-40-digit-github-token»\"\n\nSo, if you get a message like this:\n\n``` markdown\nAPI rate limit exceeded for github_username.\nSee: https://developer.github.com/v3/#rate-limiting\n```\n\nIt's time to create this token! (Or, wait an hour for GitHub to reset your unauthenticated request limit.)\n\n## Migrating from a manual changelog\n\nKnowing how dedicated you are to your project, you probably haven't been waiting for `github-changelog-generator` to keep a changelog.\nBut you probably don't want your project's open issues and PRs for all past features listed in your historic changelog, either.\n\nThat's where `--base \u003cyour-manual-changelog.md\u003e` comes in handy!\nThis option lets append your old manual changelog to the end of the generated entries.\n\nIf you have a `HISTORY.md` file in your project, it will automatically be picked as the static historical changelog and appended.\n\n### Rake task\n\nYou love `rake`? We do, too! So, we've made it even easier for you:\nwe've provided a `rake` task library for your changelog generation.\n\nConfigure the task in your `Rakefile`:\n\n```ruby\nrequire 'github_changelog_generator/task'\n\nGitHubChangelogGenerator::RakeTask.new :changelog do |config|\n  config.user = 'username'\n  config.project = 'project-name'\n  config.since_tag = '0.1.14'\n  config.future_release = '0.2.0'\nend\n```\n\nAll command-line options can be passed to the `rake` task as `config`\nparameters. And since you're naming the `rake` task yourself, you can create\nas many as you want.\n\nYou can look for params names from the [parser source code (#setup_parser)](https://github.com/github-changelog-generator/github-changelog-generator/blob/master/lib/github_changelog_generator/parser.rb). For example, to translate the bugs label to Portuguese, instead of setting `config.bugs_label`, you have to set `config.bug_prefix`, and so on.\n\n## Features and advantages of this project\n\n- Generate canonical, neat changelog file, with default sections that follow [basic changelog guidelines](http://keepachangelog.com) :gem:\n- Optionally generate **Unreleased** changes (closed issues that have not released yet) :dizzy:\n- **GitHub Enterprise support** via command line options! :factory:\n- Flexible format **customization**:\n    - **Customize** issues that **should be added** to changelog :eight_spoked_asterisk:\n    - **Custom date formats** supported (but keep [ISO 8601](http://xkcd.com/1179/) in mind!) :date:\n    - Manually specify the version that fixed an issue (for cases when the issue's Closed date doesn't match) by giving the issue's `milestone` the same name as the tag of version :pushpin:\n    - Automatically **exclude specific issues** that are irrelevant to your changelog (by default, any issue labeled `question`, `duplicate`, `invalid`, or `wontfix`) :scissors:\n- **Distinguish** issues **by labels**. :mag_right:\n    - Merged pull requests (all merged pull-requests) :twisted_rightwards_arrows:\n    - Bug fixes (issues labeled `bug`) :beetle:\n    - Enhancements (issues labeled `enhancement`) :star2:\n    - Issues (closed issues with no labels) :non-potable_water:\n    - Plus any additional custom label-to-section mappings you want :gear:\n\n- Manually include or exclude issues by labels :wrench:\n- Customize lots more! Tweak the changelog to fit your preferences :tophat:\n(*See `github_changelog_generator --help`  for details)*\n\n### Using the summary section feature\n\nFor each version, you can add a _release summary_ with text, images, gif animations,\netc, and show new features and notes clearly to the user. This is done using GitHub metadata.\n\n**Example**: adding the release summary for v1.0.0:\n\n1. Create a new GitHub Issue\n2. In the Issue's _Description_ field, add your release summary content\n```\n![image](https://user-images.githubusercontent.com/12690315/45935880-006a8200-bfeb-11e8-958e-ff742ae66b96.png)\n\nHello, World! :tada:\n```\n3. Set the Issue Label `release-summary` and add it to the GitHub Milestone `v1.0.0`\n4. Close the Issue and execute `github-changelog-generator`\n5. The result looks like this:\n\u003e ## [v1.0.0](https://github.com/github-changelog-generator/github-changelog-generator/tree/1.0.0) (2014-11-07)\n\u003e [Full Changelog](https://github.com/github-changelog-generator/github-changelog-generator/compare/0.1.0...1.0.0)\n\u003e\n\u003e ![image](https://user-images.githubusercontent.com/12690315/45935880-006a8200-bfeb-11e8-958e-ff742ae66b96.png)\n\u003e\n\u003e Hello, World! :tada:\n\u003e\n\u003e **Implemented enhancements:**\n\u003e - Add some features\n\n### Alternatives\n\nHere is a [wikipage list of alternatives](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Alternatives) that I found. But none satisfied my requirements.\n\n*If you know other projects, feel free to edit this Wiki page!*\n\n\n### Projects using this library\n\nHere's a [wikipage list of projects](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Projects-using-GitHub-Changelog-Generator).\n\nIf you've used this project in a live app, please let me know! Nothing makes me happier than seeing someone else take my work and go wild with it.\n\n*If you are using `github_changelog_generator` to generate your project's changelog, or know of other projects using it, please [add it to this list](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Projects-using-GitHub-Changelog-Generator).*\n\n## Practical Use Cases\n\n### Creating GitHub Release Notes\n\n`github_changelog_generator` can be used in combination with the [github cli](https://cli.github.com/) to create release notes.  Use the `--since-tag` and `--output` options of `github_changelog_generator` to create a changelog for the current release and store the results in a file.  In the\nexample below, version `2.0.0` is the current release and version `1.0.0` is the previous release.\n\n```\nmkdir -p build\ngithub_changelog_generator \\\n  --since-tag 1.0.0 \\\n  --output build/changelog.md\n```\n\nThen use the [release create](https://cli.github.com/manual/gh_release_create) feature of the github cli to create a new github release\n\n```\ngh release create 2.0.0 \\\n  --notes-file build/changelog.md \\\n  --title 2.0.0\n```\n\n## Am I missing some essential feature?\n\n- **Nothing is impossible!**\n\n- Open an [issue](https://github.com/github-changelog-generator/github-changelog-generator/issues/new/choose) and let's make the generator better together!\n\n- *Bug reports, feature requests, patches, and well-wishes are always welcome.* :heavy_exclamation_mark:\n\n## FAQ\n\n- ***I already use GitHub Releases. Why do I need this?***\n\nGitHub Releases is a very good thing. And it's very good practice to maintain it. (Not a lot of people are using it yet!) :congratulations:\n\n*BTW: I would like to support GitHub Releases in [next releases](https://github.com/github-changelog-generator/github-changelog-generator/issues/56) ;)*\n\nI'm not trying to compare the quality of handwritten and auto-generated logs. That said....\n\nAn auto-generated changelog really helps, even if you manually fill in the release notes!\n\n- **I want to define my own label-to-section mapping, how can I do it?**\n\nThis is possible using either the ``add-sections`` or ``configure-sections``\nentry in ``.github_changelog_generator``. For example, to add a single new\nentry called \"Maintenance\" that will catch PRs tagged with your ``maintenance``\nlabel, you can add to ``.github_changelog_generator`` the line:\n```\nadd-sections= {\"maintenance\":{\"prefix\":\"**Project maintenance**\",\"labels\":[\"maintenance\"]}}\n```\nA similar approach can be used via ``configure-sections`` to set all section\nproperties (including adding new ones!).\n\n- ***My Ruby version is very old, can I use this?***\n\nWhen your Ruby is old, and you don't want to upgrade, and you want to\ncontrol which libraries you use, you can use Bundler.\n\nIn a Gemfile, perhaps in a non-deployed `:development` group, add this\ngem:\n\n```ruby\ngroup :development do\n  gem 'github_changelog_generator', require: false\nend\n```\n\nThen you can keep back dependencies like rack, which currently is only\ncompatible with Ruby \u003e= 2.2.2. So, use an older version for your app by\nadding a line like this to the Gemfile:\n\n```\ngem 'rack', '~\u003e 1.6'\n```\n\nThis way, you can keep on using github_changelog_generator, even if you\ncan't get the latest version of Ruby installed.\n\n- ***Windows: 1.14.x wants to create a file on an invalid path. Why?***\n\nWindows: [v1.14.0 introduced a bug where it attempts to create /tmp/github_changelog-logger.log... which isn't a valid path on Windows and thus fails](https://github.com/github-changelog-generator/github-changelog-generator/issues/458)\n\nWorkaround: Create a `C:\\tmp`.\n\n## Contributing\n\nWould you like to contribute to this project? [CONTRIBUTING.md] has all the details on how to do that.\n\n[CONTRIBUTING.md]: CONTRIBUTING.md\n\n## Contact us\n[Join the chat at gitter : github-changelog-generator](https://gitter.im/github-changelog-generator/chat?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n## License\n\nGitHub Changelog Generator is released under the [MIT License](http://www.opensource.org/licenses/MIT).\n","funding_links":["https://github.com/sponsors/skywinder","https://github.com/sponsors/olleolleolle","https://patreon.com/[\"skywinder\", \"olleolleolle\"]"],"categories":["Ruby","Awesome Ruby CLIs","Project banner","Documentation and Presentation","Ruby (8)","\u003e 3k ★","Uncategorized","HarmonyOS","ruby","github-api","Examples","Changelog Tools","Documentation","Release Management Tools"],"sub_categories":["Generating","Uncategorized","Windows Manager","Generators","Changelog Generators"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub-changelog-generator%2Fgithub-changelog-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub-changelog-generator%2Fgithub-changelog-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub-changelog-generator%2Fgithub-changelog-generator/lists"}