Gradle Changelog Plugin

November 25, 2025 · View on GitHub

A Gradle plugin providing tasks and helper methods to simplify working with a changelog that is managed in the keep a changelog style.

Note

This project requires Gradle 6.8 or newer

Upgrade Gradle Wrapper with ./gradlew wrapper --gradle-version 8.3

Usage
Configuration
Tasks
Extension Methods
Classes
Helper Methods
Usage Examples
Changelog
Contributing
License

Usage

The latest available version is:

Note

The patchPluginXml task is defined in Gradle IntelliJ Plugin

build.gradle.kts (Kotlin)

import org.jetbrains.changelog.Changelog
import org.jetbrains.changelog.ChangelogSectionUrlBuilder
import org.jetbrains.changelog.date

plugins {
    id("org.jetbrains.changelog") version "..."
}

tasks {
    // ...

    patchPluginXml {
        changeNotes = provider {
            changelog.renderItem(
                changelog
                    .getUnreleased()
                    .withHeader(false)
                    .withEmptySections(false),
                Changelog.OutputType.HTML
            )
        }
    }
}

changelog {
    version = "1.0.0"
    path = file("CHANGELOG.md").canonicalPath
    header = provider { "[${version.get()}] - ${date()}" }
    headerParserRegex = """(\d+\.\d+)""".toRegex()
    introduction =
        """
        My awesome project that provides a lot of useful features, like:
        
        - Feature 1
        - Feature 2
        - and Feature 3
        """.trimIndent()
    itemPrefix = "-"
    keepUnreleasedSection = true
    unreleasedTerm = "[Unreleased]"
    groups = listOf("Added", "Changed", "Deprecated", "Removed", "Fixed", "Security")
    lineSeparator = "\n"
    combinePreReleases = true
    sectionUrlBuilder = object : ChangelogSectionUrlBuilder {
        override val extraParams = mapOf("branch" to "main")
        override fun build(repositoryUrl: String, currentVersion: String?, previousVersion: String?, isUnreleased: Boolean) = "foo"
    }
    outputFile = file("release-note.txt")
}

build.gradle (Groovy)

import org.jetbrains.changelog.Changelog
import org.jetbrains.changelog.ChangelogSectionUrlBuilder
import org.jetbrains.changelog.ExtensionsKt

plugins {
    id 'org.jetbrains.changelog' version '...'
}

apply plugin: 'org.jetbrains.changelog'

intellij {
    // ...

    patchPluginXml {
        changeNotes = provider {
            changelog.renderItem(
                changelog
                    .getUnreleased()
                    .withHeader(false)
                    .withEmptySections(false),
                Changelog.OutputType.HTML
            )
        }
    }
}

changelog {
    version = "1.0.0"
    path = file("CHANGELOG.md").canonicalPath
    header = "[${-> version.get()}] - ${ExtensionsKt.date("yyyy-MM-dd")}"
    headerParserRegex = ~/(\d+\.\d+)/
    introduction = """
        My awesome project that provides a lot of useful features, like:
        
        - Feature 1
        - Feature 2
        - and Feature 3
    """.stripIndent()
    itemPrefix = "-"
    keepUnreleasedSection = true
    unreleasedTerm = "[Unreleased]"
    groups = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
    lineSeparator = "\n"
    combinePreReleases = true
    sectionUrlBuilder = new ChangelogSectionUrlBuilder() {
        @Override
        Map<String, String> getExtraParams() {
            return ["branch": "main"]
        }

        @Override
        String build(String repositoryUrl, String currentVersion, String previousVersion, boolean isUnreleased) {
            return "foo"
        }
    }
    outputFile = file("release-note.txt")
}

Configuration

Plugin can be configured with the following properties set in the changelog {} closure:

Property	Description
`versionPrefix`	Version prefix used to compare tags.	Type: `String` Default value: `v`
`version`	Current version. By default, project's version is used.	Type: `String` Default value: `project.version`
`path`	Path to the changelog file.	Type: `String` Default value: `file("CHANGELOG.md").cannonicalPath`
`preTitle`	Optional content placed before the `title`.	Type: `String?` Default value: `null`
`title`	The changelog title set as the top-lever header – `#`.	Type: `String` Default value: `"Changelog"`
`introduction`	Optional content placed after the `title`.	Type: `String?` Default value: `null`
`header`	Header value used when patching the Unreleased section with text containing the current version.	Type: `String` Default value: `provider { "${version.get()} - ${date()}" }`
`headerParserRegex`	`Regex`/`Pattern`/`String` used to extract version from the header string.	Type: `Regex` / `Pattern` / `String` Default value: `null`, fallbacks to `SEM_VER_REGEX`
`unreleasedTerm`	Unreleased section name.	Type: `String` Default value: `"[Unreleased]"`
`keepUnreleasedSection`	Add an unreleased empty section on the top of the changelog after running the patching task.	Type: `Boolean` Default value: `true`
`patchEmpty`	Patches changelog even if no release note is provided.	Type: `Boolean` Default value: `true`
`groups`	List of groups created with a new Unreleased section.	Type: `String` Default value: `["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]`
`itemPrefix`	Single item's prefix, allows to customise the bullet sign.	Type: `String` Default value: `"-"`
`combinePreReleases`	Combines pre-releases (like `1.0.0-alpha`, `1.0.0-beta.2`) into the final release note when patching.	Type: `Boolean` Default value: `true`
`lineSeparator`	Line separator used for generating changelog content.	Type: `String` Default value: `"\n"` or determined from the existing file
`repositoryUrl`	The GitHub repository URL used to build release links. If provided, leads to the GitHub comparison page.	Type: `String?` Default value: `null`
`outputFile`	Output file to write the changelog content to when using the `getChangelog` task.	Type: `RegularFileProperty` Default value: `null`
`sectionUrlBuilder`	Function to build a single URL to link section with the GitHub page to present changes within the given release.	Type: `ChangelogSectionUrlBuilder` Default value: Common `ChangelogSectionUrlBuilder` implementation

Note

The header closure has the delegate explicitly set to the extension's context for the sake of the Configuration cache support.

Custom URL Builder for Non-GitHub Repositories

The sectionUrlBuilder property allows you to customize URL generation for different Git hosting platforms like Bitbucket, GitLab, or self-hosted repositories. You can pass extra parameters (like branch names) by overriding the extraParams property.

Bitbucket Example (Kotlin DSL):

changelog {
    repositoryUrl = "https://bitbucket.org/myorg/myrepo"
    sectionUrlBuilder = object : ChangelogSectionUrlBuilder {
        override val extraParams = mapOf("branch" to "main")

        override fun build(
            repositoryUrl: String,
            currentVersion: String?,
            previousVersion: String?,
            isUnreleased: Boolean,
        ): String {
            val branch = extraParams["branch"] ?: "master"
            return when {
                isUnreleased -> when (previousVersion) {
                    null -> "$repositoryUrl/commits/branch/$branch"
                    else -> "$repositoryUrl/branches/compare/$branch%0D$previousVersion"
                }
                previousVersion == null -> "$repositoryUrl/commits/tag/$currentVersion"
                else -> "$repositoryUrl/branches/compare/$currentVersion%0D$previousVersion"
            }
        }
    }
}

GitLab Example (Groovy):

changelog {
    repositoryUrl = "https://gitlab.com/myorg/myrepo"
    sectionUrlBuilder = new ChangelogSectionUrlBuilder() {
        @Override
        Map<String, String> getExtraParams() {
            return ["branch": "main"]
        }

        @Override
        String build(String repositoryUrl, String currentVersion, String previousVersion, boolean isUnreleased) {
            def branch = extraParams.get("branch") ?: "master"
            if (isUnreleased) {
                return previousVersion ? "$repositoryUrl/-/compare/$previousVersion...$branch" : "$repositoryUrl/-/commits/$branch"
            } else {
                return previousVersion ? "$repositoryUrl/-/compare/$previousVersion...$currentVersion" : "$repositoryUrl/-/commits/$currentVersion"
            }
        }
    }
}

Tasks

The plugin introduces the following tasks:

Task	Description
`getChangelog`	Retrieves changelog for the specified version.
`initializeChangelog`	Creates a new changelog file with an unreleased section and empty groups.
`patchChangelog`	Updates the unreleased section to the given version.

`getChangelog`

Retrieves changelog for the specified version.

Options

Option	Type	Default value	Description
`--no-header`	`Boolean`	`false`	Omits the section header in the changelog output.
`--no-summary`	`Boolean`	`false`	Omits the section summary in the changelog output.
`--no-links`	`Boolean`	`false`	Omits links in the changelog output.
`--no-empty-sections`	`Boolean`	`false`	Omits empty sections in the changelog output.
`--project-version`	`String?`	`null`	Returns change notes for the specified project version.
`--unreleased`	`Boolean`	`false`	Returns change notes for an unreleased section.
`--output-file`	`String?`	`null`	File to write the changelog content to.

Examples

$ ./gradlew getChangelog --console=plain -q --no-header --no-summary

### Added
- Initial project scaffold
- GitHub Actions to automate testing and deployment
- Kotlin support

$ ./gradlew getChangelog --output-file=build/changelog.md
$ cat build/changelog.md

## [1.0.0]

Initial release.

### Added
- Initial project scaffold
- GitHub Actions to automate testing and deployment
- Kotlin support

[1.0.0]: https://github.com/JetBrains/gradle-changelog-plugin/releases/tag/v1.0.0

`initializeChangelog`

Creates a new changelog file with an unreleased section and empty groups.

Examples

$ ./gradlew initializeChangelog
$ cat CHANGELOG.md

## [Unreleased]
### Added
- Example item

### Changed

### Deprecated

### Removed

### Fixed

### Security

`patchChangelog`

Updates the unreleased section to the given version.

Options

Option	Type	Default value	Description
`--release-note`	`String?`	`null`	Use custom release note to create new changelog entry.

Warning

Content provided with the --release-note option will override the existing release note for the latest unreleased entry.

Examples

$ cat CHANGELOG.md
## [Unreleased]
### Added
- A based new feature
 
$ ./gradlew patchChangelog
$ cat CHANGELOG.md

## [Unreleased]
### Added

## [1.0.0]
### Added
- A based new feature

$ cat CHANGELOG.md
## [Unreleased]
### Added
- This note will get overridden by the `--release-note`

$ ./gradlew patchChangelog --release-note='- Foo'
$ cat CHANGELOG.md
## [Unreleased]
### Added

## [1.0.0]
- Foo

Extension Methods

All the methods are available via the changelog extension and allow for reading the changelog file within the Gradle tasks to provide the latest (or specific) change notes.

Note

The following methods depend on the changelog extension set in the Configuration build phase. For safe access and process of your changelog file, we recommend accessing the changelog extension within Gradle closures as presented in the Usage section.

`changelog.get(version: String): Changelog.Item`

The method returns a Changelog.Item? object for the specified version. Throws MissingVersionException if the version is not available.

Parameters

Parameter	Type	Description
`version`	`String`	Change note version.

`changelog.getUnreleased(): Changelog.Item`

The method returns a Changelog.Item object for the unreleased version. Throws MissingVersionException if the version is not available.

`changelog.getLatest(): Changelog.Item`

The method returns the latest released Changelog.Item object (first on the list). Throws MissingVersionException if the version is not available.

`changelog.has(version: String): Boolean`

The method checks if the given version exists in the changelog.

Parameters

Parameter	Type	Description
`version`	`String`	Change note version.

`changelog.render(outputType: Changelog.OutputType): String`

Renders the whole Changelog object to string based on the given outputType.

Parameters

Parameter	Type	Description
`outputType`	`Changelog.OutputType`	Output type, see Changelog.OutputType

`changelog.renderItem(item: Changelog.Item, outputType: Changelog.OutputType): String`

Renders the given Changelog.Item object to string based on the given outputType.

Parameters

Parameter	Type	Description
`item`	`Changelog.Item`	Item to render, see Changelog.Item
`outputType`	`Changelog.OutputType`	Output type, see Changelog.OutputType

`changelog.getInstance(): Changelog`

Returns the Changelog instance shared among all the tasks. See Changelog for more details.

Classes

`Changelog` class

The Changelog class is a wrapper for the Changelog file. It provides methods to read and write the changelog file.

Properties

Name	Type	Description
`preTitle`	`String`	Optional content placed before the `title`.
`title`	`String`	The changelog title set as the top-lever header – `#`.
`introduction`	`String`	Optional content placed after the `title`.
`items`	`Map<String, Changelog.Item>`	List of all items available in the changelog stored in a map of `version` to `Changelog.Item`.
`unreleasedItem`	`Changelog.Item?`	An instance of the unreleased item, may be `null`.
`releasedItems`	`List<Changelog.Item>`	List of already released item instances.
`links`	`Map<String, String>`	List of all links stored at the end of the changelog in a map of `id` to `url`.

Methods

Name	Return type	Description
`get(version: String)`	`Changelog.Item`	Returns item for the given `version`. Throws `MissingVersionException` if missing.
`getLatest()`	`Changelog.Item`	Returns the latest released item. Throws `MissingVersionException` if missing.
`has(version: String)`	`Boolean`	Checks if item with the given `version` exists.
`render(outputType: Changelog.OutputType)`	`String`	Renders the whole `Changelog` object to string based on the given `outputType`.
`renderItem(item: Changelog.Item, outputType: Changelog.OutputType)`	`String`	Renders the given `Changelog.Item` object to string based on the given `outputType`.

`Changelog.OutputType` enum

Name	Description
`MARKDOWN`	Default, Markdown content format.
`PLAIN_TEXT`	Plain text with no Markdown syntax generated.
`HTML`	HTML content created out of Markdown version.

`Changelog.Item` class

Methods described in the above section return Changelog.Item object, which is a representation of the single changelog section for the specific version.

It provides a couple of properties and methods that allow altering the output form of the change notes:

Properties

Name	Type	Description
`version`	`String`	Item version.
`header`	`String`	Literal representation of the given item – may contain version with extra meta, like date.
`summary`	`String`	Optional summary of the release item.
`isUnreleased`	`Boolean`	Determines if an item is released or not.

Methods

Name	Description	Returned type
`withHeader(Boolean)`	Includes header part in the output.	`Changelog.Item`
`withLinkedHeader(Boolean)`	Adds link to the version in the header.	`Changelog.Item`
`withSummary(Boolean)`	Includes summary part.	`Changelog.Item`
`withLinks(Boolean)`	Returns links used in the release section at the end.	`Changelog.Item`
`withEmptySections(Boolean)`	Prints empty sections.	`Changelog.Item`
`withFilter(Boolean)`	Applies custom filter to the returned entries.	`Changelog.Item`
`toText()`	Deprecated. Use `changelog.renderItem(item)`	`String`
`toPlainText()`	Deprecated. Use `changelog.renderItem(item, Changelog.OutputType.PLAIN_TEXT)`	`String`
`toString()`	Deprecated. Use `changelog.renderItem(item, Changelog.OutputType.MARKDOWN)`	`String`
`toHTML()`	Deprecated. Use `changelog.renderItem(item, Changelog.OutputType.HTML)`	`String`

Helper Methods

Name	Description	Returned type
`date(pattern: String = "yyyy-MM-dd")`	Shorthand for retrieving the current date in the given format.	`String`
`markdownToHTML(input: String, lineSeparator: String = "\n")`	Converts given Markdown content to HTML output.	`String`
`markdownToPlainText(input: String, lineSeparator: String)`	Converts given Markdown content to Plain Text output.	`String`

Note

To use package-level Kotlin functions in Groovy, you need to import the containing file as a class:
import org.jetbrains.changelog.ExtensionsKt

changelog {
  header = { "[$version] - ${ExtensionsKt.date('yyyy-MM-dd')}" }
}