Changelog

You may define either content or contentTemplate, with the latter taking precedence over the former.

Changelog formatting applies only to the automatically generated changelog, that is, formatting won’t occur if the external property is set. Format applies only to local commits at the moment, the use of labelers is highly encouraged.

The changelog.format property only accepts the following name templates:

Key	Description
commitShortHash	head commit hash abbreviated to 7 characters
commitFullHash	head commit hash
commitTitle	first line of the commit message
commitAuthor	full name of the commit author
commitsUrl	commits URl as provided by the Git host

Key

Description

commitShortHash

head commit hash abbreviated to 7 characters

commitFullHash

head commit hash

commitTitle

first line of the commit message

commitAuthor

full name of the commit author

commitsUrl

commits URl as provided by the Git host

The content and contentTemplate accept all Name Templates, take special consideration on {{changelogChanges}} and {{changelogContributors}} as they define the parsed commits.

Templates

The default location for templates is:

src/jreleaser/templates

The following list shows the filenames that may be used to override default templates:

changelog.tpl

Commits

If you wish to generate the changelog between two tags, with tags in between, you may configure previousTagName. It generates the changelog based on all commits between the two tags. (git log <previousTagName>…<tagName>).

If not defined, it will default to the logical previous tag of the defined tagName.

Contributors

Contributor names are added to the formatted changelog by default. You may choose to provide a custom format or disable this behavior completely. The contributors.format property accepts the following templates:

Key	Description
contributorName	the contributor’s name as plain text
contributorNameAsLink	the contributor’s name as a link
contributorUsername	the contributor’s username as plain text
contributorUsernameAsLink	the contributor’s username as a link

Key

Description

contributorName

the contributor’s name as plain text

contributorNameAsLink

the contributor’s name as a link

contributorUsername

the contributor’s username as plain text

contributorUsernameAsLink

the contributor’s username as a link

The use of {{contributorNameAsLink}}, {{contributorUsername}}, or {{contributorUsernameAsLink}} incurs on a network call to the remote service to find out information related to the given contributor.

Use a - or * character as prefix in format to list each contributor on its own row.

The following configuration

release:
  github:
    username: aalmiray
    overwrite: true
    draft: false
    sign: true
    changelog:
      formatted: ALWAYS
      format: '- {{commitShortHash}} {{commitTitle}}'
      labelers:
        - label: 'feature'
          title: 'Resolves #'
          body: 'Resolves #'
        - label: 'issue'
          title: 'Fixes #'
          body: 'Fixes #'
        - label: 'issue'
          title: 'Relates to #'
          body: 'Relates to #'
        - label: 'task'
          title: '[chore]'
      categories:
        - title: '🚀 Features'
          labels:
            - 'feature'
        - title: '✅ Issues'
          labels:
            - 'issue'
        - title: '🧰 Tasks'
          labels:
            - 'task'
      replacers:
        - search: '\[chore\] '

Generates a changelog similar to

Presets

Presets define conventions applicable to:

labelers
categories
replacers
hide
- categories
- contributors

You may apply a preset while at the same time define additional elements. Your configuration takes precedence over the preset’s, allowing you to add/merge. For the time being you can’t remove a setting defined by a preset.

Conventional Commits

Commit messages that follow the Conventional Commits specification will be automatically labeled and categorized. The following table shows mappings that you may use when this preset is applied:

Category	Label	Prefix
🚀 Features	feat	feat:
🐛 Fixes	fix	fix:
♻️ ️Changes	perf	perf:
♻️ ️Changes	refactor	refactor:
♻️ ️Changes	revert	revert:
♻️ ️Changes	style	style:
🧰 Tasks	chore	chore:
🛠 Build	test	test:
🛠 Build	build	build:
🛠 Build	ci	ci:
📝 Documentation	docs	docs:

Example

The following configuration

release:
  github:
    changelog:
      formatted: ALWAYS
      preset: 'conventional-commits'
      format: '- {{commitShortHash}} {{commitTitle}}'

For a project with the following commits

* bda315f (HEAD -> main, upstream/main) docs: Add missing "`". (#1048)
* 3adf1b5 fix: Do not force .java suffix for Quarkus based templates (#1039)
* 013f328 feat: Startup scripts now use User-Agent header for downloads (#1037)
* 47e2a81 fix: This fixes extraneous jbang.cmd output (#1041)
* fe08627 refactor: Simplified `jbang.cmd` (#1038)
* ea65d99 fix: add hint to user they can get updated catalog using --fresh (#1040)
* 8ac258c fix: No longer pass Accept header (#1036)
* 95a715e [patch] fix linux based java download
* 275d31a fix: archive type for foojay. Fixes #1035
* d42951d [patch]
* 98866f1 fix: Add itest for issue #1019 (#1033)
* 20514c7 fix: Now really fixed updating on Windows (#1031)
* 9ed4116 [minor]
* fb45502 chore: use jreleaser 0.7
* 7419590 fix: edit now honors JBANG_EDITOR again
* 3955647 fix: Not checking for new version on first run anymore (#1023)
* 5e16e22 fix:  jbang edit suggests incorrect command when template renames out… (#1020)
* 3ac5561 fix: --deps now gets special javafx treatments as //DEPS does (#1017)
* 52b2377 fix: Fixed link to "Usage on Windows" (#1026)
* 8d5ea6a fix: Fixed download URL in `jbang` script (#1021)
* b750ebb fix: kotlin edit now link to source rather than cache location (#1015)
* 6f87c70 chore: eliminate warnings from code base (#1011)
* f842666 docs: Update spotless pre-commit hook url (#1009)
* d297667 [patch] fix java 17 downloads
* f6a32db fix: use termurin for java 17
* 43b2c72 chore: remove j'bang from choco name, its just JBang
* da0c971 fix: proper nuget
* 30cf637 (tag: v0.80.1) [patch]

Generates a changelog similar to

jreleaser changelog preset conventional commits

Gitmoji

Commit messages that follow the Gitmoji convention will be automatically labeled and categorized. The following table shows mappings that you may use when this preset is applied:

Category	Label	Emoji	Keyword
Merge	merge	🔀	:twisted_rightwards_arrows:
Added	added	✨	:sparkles:
Added	added	🎉	:tada:
Added	added	✅	:white_check_mark:
Added	added	👷	:construction_worker:
Added	added	📈	:chart_with_upwards_trend:
Added	added	➕	:heavy_plus_sign:
Added	added	🔊	:loud_sound:
Changed	changed	🎨	:art:
Changed	changed	⚡️	:zap:
Changed	changed	💄	:lipstick:
Changed	changed	🚨	:rotating_light:
Changed	changed	📌	:pushpin:
Changed	changed	♻️	:recycle:
Changed	changed	🔧	:wrench:
Changed	changed	🔨	:hammer:
Changed	changed	⏪	:rewind:
Changed	changed	👽	:alien:
Changed	changed	🚚	:truck:
Changed	changed	🍱	:bento:
Changed	changed	♿️	:wheelchair:
Changed	changed	💬	:speech_balloon:
Changed	changed	🗃	:card_file_box:
Changed	changed	🚸	:children_crossing:
Changed	changed	🏗	:building_construction:
Changed	changed	📱	:iphone:
Changed	changed	📦	:package:
Breaking	breaking_changes	💥	:boom:
Deprecated	deprecated	🗑	:wastebasket:
Removed	Removed	➖	:heavy_minus_sign:
Removed	Removed	🔥	:fire:
Removed	Removed	🔇	:mute:
Removed	Removed	⚰️	:coffin:
Fixed	fixed	🐛	:bug:
Fixed	fixed	🚑	:ambulance:
Fixed	fixed	🍎	:apple:
Fixed	fixed	🍏	:green_apple:
Fixed	fixed	🐧	:penguin:
Fixed	fixed	🏁	:checkered_flag:
Fixed	fixed	🤖	:robot:
Fixed	fixed	💚	:green_heart:
Fixed	fixed	✏️	:pencil2:
Fixed	fixed	🩹️	:adhesive_bandage:
Security	security	🔒️	:lock:
Security	security	🛂	:passport_control:
Documentation	documentation	📝	:pencil:
Documentation	documentation	📝	:memo:
Documentation	documentation	🌐	:globe_with_meridians:
Documentation	documentation	📄	:page_facing_up:
Documentation	documentation	💡	:bulb:
Dependencies	dependencies	⬆️	:arrow_up:
Dependencies	dependencies	⬇️	:arrow_down:
Miscellaneous	misc	💩	:poop:
Miscellaneous	misc	🚧	:construction:
Miscellaneous	misc	🍻	:beers:
Miscellaneous	misc	👥	:busts_in_silhouette:
Miscellaneous	misc	🤡	:clown_face:
Miscellaneous	misc	🥚	:egg:
Miscellaneous	misc	🙈	:see_no_evil:
Miscellaneous	misc	📸	:camera_flash:
Miscellaneous	misc	⚗️	:alembic:
Miscellaneous	misc	🔍	:mag:
Miscellaneous	misc	🥅	:goal_net:
Miscellaneous	misc	🧐	:monocle_face:
Miscellaneous	misc	🧪	:test_tube:
Miscellaneous	misc	👔	:necktie:
Miscellaneous	misc	👌	:ok_hand:
Release	release	🚀	:rocket:
Release	release	🔖	:bookmark:

Category

Label

Emoji

Keyword

Merge

merge

🔀

:twisted_rightwards_arrows:

Added

added

✨

:sparkles:

Added

added

🎉

:tada:

Added

added

✅

:white_check_mark:

Added

added

👷

:construction_worker:

Added

added

📈

:chart_with_upwards_trend:

Added

added

➕

:heavy_plus_sign:

Added

added

🔊

:loud_sound:

Changed

changed

🎨

:art:

Changed

changed

⚡️

:zap:

Changed

changed

💄

:lipstick:

Changed

changed

🚨

:rotating_light:

Changed

changed

📌

:pushpin:

Changed

changed

♻️

:recycle:

Changed

changed

🔧

:wrench:

Changed

changed

🔨

:hammer:

Changed

changed

⏪

:rewind:

Changed

changed

👽

:alien:

Changed

changed

🚚

:truck:

Changed

changed

🍱

:bento:

Changed

changed

♿️

:wheelchair:

Changed

changed

💬

:speech_balloon:

Changed

changed

🗃

:card_file_box:

Changed

changed

🚸

:children_crossing:

Changed

changed

🏗

:building_construction:

Changed

changed

📱

:iphone:

Changed

changed

📦

:package:

Breaking

breaking_changes

💥

:boom:

Deprecated

deprecated

🗑

:wastebasket:

Removed

➖

:heavy_minus_sign:

Removed

🔥

:fire:

Removed

🔇

:mute:

Removed

⚰️

:coffin:

Fixed

fixed

🐛

:bug:

Fixed

fixed

🚑

:ambulance:

Fixed

fixed

🍎

:apple:

Fixed

fixed

🍏

:green_apple:

Fixed

fixed

🐧

:penguin:

Fixed

fixed

🏁

:checkered_flag:

Fixed

fixed

🤖

:robot:

Fixed

fixed

💚

:green_heart:

Fixed

fixed

✏️

:pencil2:

Fixed

fixed

🩹️

:adhesive_bandage:

Security

security

🔒️

:lock:

Security

security

🛂

:passport_control:

Documentation

documentation

📝

:pencil:

Documentation

documentation

📝

:memo:

Documentation

documentation

🌐

:globe_with_meridians:

Documentation

documentation

📄

:page_facing_up:

Documentation

documentation

💡

:bulb:

Dependencies

dependencies

⬆️

:arrow_up:

Dependencies

dependencies

⬇️

:arrow_down:

Miscellaneous

misc

💩

:poop:

Miscellaneous

misc

🚧

:construction:

Miscellaneous

misc

🍻

:beers:

Miscellaneous

misc

👥

:busts_in_silhouette:

Miscellaneous

misc

🤡

:clown_face:

Miscellaneous

misc

🥚

:egg:

Miscellaneous

misc

🙈

:see_no_evil:

Miscellaneous

misc

📸

:camera_flash:

Miscellaneous

misc

⚗️

:alembic:

Miscellaneous

misc

🔍

:mag:

Miscellaneous

misc

🥅

:goal_net:

Miscellaneous

misc

🧐

:monocle_face:

Miscellaneous

misc

🧪

:test_tube:

Miscellaneous

misc

👔

:necktie:

Miscellaneous

misc

👌

:ok_hand:

Release

release

🚀

:rocket:

Release

release

🔖

:bookmark:

The following commit messages are equivalent:

🐛 Random number generator always returns 4.
:bug: Random number generator always returns 4.

Keywords are automatically replaced by their corresponding emoji in the generated changelog.

Example

The following configuration

release:
  github:
    changelog:
      formatted: ALWAYS
      preset: 'gitmoji'
      format: '- {{commitShortHash}} {{commitTitle}}'

For a project with the following commits

* 3dabd57 :bookmark: Release v2.2.0
* a9b1bfe :bug: Fix init command (#204)
* cdf76f9 :pushpin: Upgrade dependencies (#191)
* f7ca721 :memo: Fix the link and update year (#197)
* ceab8dc :sparkles: Add Cargo preset (#199)
* d2ee43d :memo: Change documentation link in README (#196)
* e06e08d :busts_in_silhouette: Add endormi as a contributor (#195)
* 5e0a971 :docs: Add the documentation site (#194)
* 20cf369 :bug: Fix a bug occuring when version is missing in configuration but passed as argument (#190)
* b12dfec :ok_hand: Take care of review
* 9a15406 :goal_net: Handle functional errors
* 4e22239 :pencil: Improve documentation about presets (#189)
* 1febf42 :wrench: Update lock file
* 1635963 :memo: Improve Workflow section (#152)
* a127469 :arrow_up: Upgrade dependencies

Generates a changelog similar to