Skip to content
Generate a markdown changelog document from a GitHub milestone.
Branch: master
Clone or download
Latest commit d4f713f Apr 13, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Use psr18 instead of guzzle. Apr 10, 2019
src/ChangelogGenerator Add --show-contributors option to output a section with a list of Apr 13, 2019
.scrutinizer.yml Changelog Generator. May 19, 2018
LICENSE Changelog Generator. May 19, 2018 Fix include-open option overriding value in ChangelogConfig. Jul 11, 2018
box.json Changelog Generator. May 19, 2018
composer.json Update phpstan dependencies. Apr 10, 2019
composer.lock Update phpstan dependencies. Apr 10, 2019 Add helper scripts for generating PHAR. Jun 7, 2018
phpstan.neon.dist Run PHPStan againsts tests folder. Jul 11, 2018
phpunit.xml.dist Changelog Generator. May 19, 2018

Changelog Generator

Build Status Scrutinizer Code Quality Code Coverage

This library will generate a changelog markdown document from a GitHub milestone. It is based off of weierophinney/changelog_generator.



You can install with composer:

$ composer require jwage/changelog-generator

Or you can download the latest changelog-generator.phar file from the releases pages.


Here is what an example changelog looks like. It was generated from the 0.0.3 milestone in GitHub for this project:


  • Total issues resolved: 7
  • Total pull requests resolved: 7
  • Total contributors: 1


You can also look at the file which is generated by this project.

Basic Usage

Generate a change log based on a GitHub milestone with the following command:

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0

Write to File

Write the generated changelog to a file with the --file option. If you don't provide a value, it will be written to the current working directory in a file named

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file

You can pass a value to --file to specify where the changelog file should be written:

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0

By default it will overwrite the file contents but you can pass the --append option to append the changelog to the existing contents.

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --append

If you want to prepend the changelog to an existing file, use the --prepend option:

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --prepend

Connecting Issues & Pull Requests

To make the changelog easier to read, we try to connect pull requests to issues by looking for #{ISSUE_NUMBER} in the body of the pull request. When the user of the issue and pull request are different github users, the changelog line will look like the following:

Filtering by Labels

You can filter the changelog by label names using the --label option:

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --label=Enhancement --label=Bug

Including Open Issues & Pull Requests

It can be convenient when preparing release notes for an upcoming release to include open issues and pull requests. For this you can use the --include-open option:

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --include-open

Configuration File

You can provide a PHP configuration file to the changelog generator if you don't want to provide the data manually each time. Put the following contents in a file named config.php:



use ChangelogGenerator\ChangelogConfig;

return [
    'changelog-generator' => (new ChangelogConfig())
        ->setLabels(['Enhancement', 'Bug'])
    'another-project' => (new ChangelogConfig())
        // ...

Then you can use the configuration file like the following:

$ ./vendor/bin/changelog-generator generate --config=config.php

By default it will generate a changelog for the first changelog config in the array returned by the file. You can use the --project option if you want to generate a changelog for a specific project in the config file:

$ ./vendor/bin/changelog-generator generate --config=config.php --project=another-project

By default if you name your config file changelog-generator-config.php, the changelog generator will look for that file if no --config option is passed.

$ ./vendor/bin/changelog-generator generate

You can override options provided by the ChangelogConfig object from the command line by passing options to the generate command:

$ ./vendor/bin/changelog-generator generate --include-open=0

GitHub Enterprise Support

You can configure the URL of your GitHub instance by using the rootGitHubUrl option. In your config.php you can pass a 5th argument to ChangelogConfig that contains an array of options:



use ChangelogGenerator\ChangelogConfig;

return [
    'changelog-generator' => (new ChangelogConfig())
        ->setLabels(['Enhancement', 'Bug'],)
        ->setOption('rootGitHubUrl', '')
You can’t perform that action at this time.