See all the options for gren.

The global options are shared between the gren release and gren changelog commands, as gren changelog --generate can create release notes and a CHANGELOG.md file, instead of getting all the releases from project release notes.

To use an option in your terminal, prefix the name with -- (e.g. gren release --data-source=commits)

To pass it to the Gren class or in the configuration file they need to be camelCase (e.g. "dataSource": "commits").



The username of the repo e.g. github-tools
short: -u value: <repo owner>


The repository name e.g. github-release-notes
short: -r value: <repository name>


The token generated with repo access
short: -T value: <github token>


Override the GitHub API URL, allows gren to connect to a private GHE installation
short: -a value: <url>


Override the release notes if exist
short: -o


Run the command in debugging mode
short: -B


Write release notes for <new-tag> using data collected until <old-tag>. If only one tag is specified, will use data until the previous tag. To run gren for all the tags, use --tags=all
short: -t value: <new-tag>..<old-tag>


Just produce release notes for the <number> last releases.
short: -l value: <number>


The informations you want to use to build release notes. 
short: -D value: <issues|commits|milestones|prs|prs-with-issues> default: issues


Filter the messages added to the release notes. Only used when --data-source used is commits 
short: -N value: <merge|commits|all> default: commits


Ignore tags that contain one of the specified strings.
short: -i value: <string1>,<string2>


Ignore commits that contain one of the specified strings.
short: -C value: <string1>,<string2>


Add a prefix to the tag version. e.g. 'v'
short: -p value: <name prefix>


Group the issues using the labels as group headings. You can set custom headings for groups of labels from a configuration file.
short: -g value: <label>


Ignore the specified labels.
short: -L value: <label1>,<label2>


Ignore issues that contains one of the specified labels.
short: -I value: <label1>,<label2>


The title that the script needs to match to link the release to the milestone. e.g. v will match v0.1.0 
short: -M value: <prefix> default: Release {{tag_name}}


Add to the release bodies only the issues that have a milestone
short: -m


Run command without console logs.
short: -q


Specify a custom config filename
short: -c value: <string>



Set the release notes as a draft.
short: -d


Set the release as a prerelease.
short: -P



Generate the changelog with gren rather than using the repo releases
short: -G


The name of the changelog file. 
short: -f value: <filename.md> default: CHANGELOG.md

Configuration file

You can create a configuration file where the task will be ran, where to specify your options. The options are the same on specified above but in camelCase e.g:

    "dataSource": "commits",
    "ignoreIssuesWith": [
    "template": {

If you need help to create the configuration file, you can run the following command and follow the instructions

gren init

Group By

Via the configuration file you can have more complex grouping, using labels in a more creative way. gren will use the keys of the given Object as titles and group all the issues that contain one or more of the labels in the value Array. A bit complex to understand? Just see the example:

    "groupBy": {
        "Enhancements:": ["enhancement", "internal"],
        "Bug Fixes:": ["bug"]

In this case gren will group all the issues labeled with enhancement and internal under the title “Enhancements: “ and all the ones with bug under the title “Bug Fixes: “.

Issues with multiple labels

In case an issue has more than a specified label (e.g. both “enhancement” and “bug”), gren will prioritise based on the order (i.e. the issue will only appear in the “Enhancements” group).


The accepted file extensions are the following:


You can configure the output of gren using templates. Set your own configuration inside the config file, which will be merged with the defaults, shown below:

module.exports = {
    "template": {
        commit: ({ message, url, author, name }) => `- [${message}](${url}) - ${author ? `@${author}` : name}`,
        issue: "- {{labels}} {{name}} [{{text}}]({{url}})",
        label: "[**{{label}}**]",
        noLabel: "closed",
        group: "\n#### {{heading}}\n",
        changelogTitle: "# Changelog\n\n",
        release: "## {{release}} ({{date}})\n{{body}}",
        releaseSeparator: "\n---\n\n"

If you’re using a .grenrc.js config file, you can use JavaScript to manipulate the templates using functions as values. The function will have an object as first parameter, containing all the values to display. i.e.

/* .grenrc.js */

module.exports = {
    template: {
        issue: function (placeholders) {
            return '- ' + placeholders.labels + ' | ' + placeholders.name.toLowerCase();