jreleaser.github.io/docs/modules/configuration/pages/release/gitlab.adoc

= GitLab

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:exclamation-triangle[]
release:
  # Repo in which the release will be created.
  # icon:exclamation-triangle[]
  gitlab:
    # Disables or enables publication to GitLab.
    # defaults to `true`.
    # icon:dot-circle[]
    enabled: true

    # Defines the connection timeout in seconds.
    # Defaults to `20`.
    # icon:dot-circle[]
    connectTimeout: 20

    # Defines the read timeout in seconds.
    # Defaults to `60`.
    # icon:dot-circle[]
    readTimeout: 60

    # The user or organization that owns the repository.
    # If unspecified, will read it from the 'origin' git remote.
    # icon:dot-circle[]
    owner: duke

    # The name of the repository.
    # If unspecified, will read it from the 'origin' git remote.
    # icon:dot-circle[]
    name: app

    # The GitLab host url.
    # Defaults to `gitlab.com`.
    # icon:exclamation-triangle[]
    host: gitlab.com

    # Username used for authoring commits. Must have write access to the repository.
    # icon:exclamation-triangle[]
    username: duke

    # Password or OAuth token with write access to the repository.
    # If left unspecified, the `JRELEASER_GITLAB_TOKEN`
    # environment variable must be defined.
    # icon:exclamation-triangle[] icon:eye-slash[]
    token: __DO_NOT_SET_HERE__

    # The tag associated with the release.
    # May define a `JRELEASER_TAG_NAME` environment variable instead.
    # If left unspecified, will use `v{{projectVersion}}`.
    # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
    tagName: v1.0.0

    # The name of the release.
    # May define a `JRELEASER_RELEASE_NAME` environment variable instead.
    # If left unspecified, will use `Release {{tagName}}`.
    # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
    releaseName: Release v1.0.0

    # Drops and creates an existing release with matching tag.
    # May define a `JRELEASER_OVERWRITE` environment variable instead.
    # Defaults to `false`.
    # icon:dot-circle[] icon:eye-slash[]
    overwrite: true

    # Appends artifacts to an existing release with matching tag,
    # useful if `overwrite` is set to `false`.
    # May define a `JRELEASER_UPDATE` environment variable instead.
    # Defaults to `false`.
    # icon:dot-circle[] icon:eye-slash[]
    update: true

    # Skips creating a tag.
    # Useful when the tag was created externally.
    # May define a `JRELEASER_SKIP_TAG` environment variable instead.
    # Defaults to `false`.
    # icon:dot-circle[] icon:eye-slash[]
    skipTag: false

    # The GitLab API endpoint to use.
    # You can skip `/api/v4` as it will be added by default.
    # Defaults to `pass:[https://gitlab.com]`.
    # icon:dot-circle[]
    apiEndpoint: pass:[https://gitlab.com]

    # Git author used to commit to the repository.
    # icon:dot-circle[]
    commitAuthor:
      # Name used when authoring commits.
      # Defaults to `jreleaserbot`.
      # icon:dot-circle[]
      name: jreleaserbot

      # E-mail used when authoring commits.
      # Defaults to `pass:[jreleaser@kordamp.org]`.
      # icon:dot-circle[]
      email: pass:[jreleaser@kordamp.org]

    # Signs commits with the configured credentials.
    # The xref:configuration:signing.adoc[] section must be configured as well.
    # Defaults to `false`.
    # icon:dot-circle[]
    sign: false

    # Changelog customization.
    # icon:dot-circle[]
    changelog:
      # Disables or enables the changelog.
      # defaults to `true`.
      # icon:dot-circle[]
      enabled: true

      # Sorts commits in ascending (oldest first) or descending (newer first).
      # Valid values are: `ASC`, `DESC`.
      # Defaults to `DESC`.
      # icon:dot-circle[]
      sort: DESC

      # Path to an external file that contains the changelog, read as is.
      # May be a relative path to the configuration file or an absolute path.
      # If unspecified, JReleaser will automatically calculate the changelog.
      # icon:dot-circle[]
      external: path/to/changelog.md

      # Create explicit markdown links for commit hashes.
      # Defaults to `false`.
      # icon:dot-circle[]
      links: false

      # Enables or disables formatting options.
      # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `NEVER`.
      # icon:dot-circle[]
      formatted: ALWAYS

      # The template to use for each change.
      # Defaults to `- {{commitShortHash}} {{commitTitle}} ({{commitAuthor}})`.
      # icon:dot-circle[] icon:file-alt[]
      change: '- {{commitShortHash}} {{commitTitle}}'

      # The template to use for the whole changelog.
      # Defaults is shown.
      # icon:dot-circle[] icon:file-alt[]
      content: |
        # Changelog

        {{changelogChanges}
        {{changelogContributors}}

      # Path to a template file that defines the contents.
      # Review the available xref:configuration:name-templates.adoc[].
      # Defaults to `src/jreleaser/templates/changelog.tpl`.
      # icon:dot-circle[]
      contentTemplate: path/to/template/changelog.tpl

      # Hide uncategorized commits.
      # Defaults to `false`.
      # icon:dot-circle[]
      hideUncategorized: true

      # A list of labels to be included.
      # Only changes matching this list will be included.
      # Defaults to empty.
      # icon:dot-circle[]
      includeLabels:
        - 'issue'

      # A list of labels to be excluded.
      # Changes matching this list will be excluded.
      # Defaults to empty.
      # icon:dot-circle[]
      excludeLabels:
        - 'issue'

      # Defines rules that apply labels to changes.
      # Matchers are evaluated independently; the label will
      # be set if at least one of the matchers meets the criteria.
      # icon:dot-circle[]
      labelers:
          # The label to be applied.
          # icon:exclamation-triangle[]
        - label: 'issue'

          # Matches the text of the first commit line.
          # icon:dot-circle[]
          title: '^fix:'

          # Matches the full text of the commit.
          # icon:dot-circle[]
          body: 'Fixes #'

      # Groups changes by category.
      # Defaults are shown.
      # icon:dot-circle[]
      categories:
        - title: '🚀 Features'
          labels:
            - 'feature'
            - 'enhancement'
        - title: '🐛 Bug Fixes'
          labels:
            - 'bug'
            - 'fix'

      # Defines rules for replacing the generated content.
      # Each replacer is applied in order.
      # icon:dot-circle[]
      replacers:
        - search: '\[chore\]\s'
          replace: ''
        - search: '/CVE-(\d{4})-(\d+)/g'
          replace: 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2'

    # A milestone associated with the release
    # icon:dot-circle[]
    milestone:
      # Close the milestone (if it exists and still active) upon release.
      # Defaults to `true`.
      # icon:dot-circle[]
      close: true

      # The name/title of the milestone.
      # May define a `JRELEASER_MILESTONE_NAME` environment variable instead.
      # Defaults to `{{tagName}}`.
      # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      name: '{{tagName}}'

    # The target branch to use.
    # May define a `JRELEASER_BRANCH` environment variable instead.
    # Defaults to the branch pointed by HEAD.
    # icon:dot-circle[] icon:eye-slash[]
    branch: main

    # The following properties define icon:dot-circle[] URL formats.
    # Defaults are shown.
    # Review the available xref:configuration:name-templates.adoc[].

    # icon:dot-circle[] icon:file-alt[]
    repoUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}]

    # icon:dot-circle[] icon:file-alt[]
    repoCloneUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}.git]

    # icon:dot-circle[] icon:file-alt[]
    commitUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/commits]

    # icon:dot-circle[] icon:file-alt[]
    downloadUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}/downloads/{{artifactFileName}}]

    # icon:dot-circle[] icon:file-alt[]
    releaseNotesUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]

    # icon:dot-circle[] icon:file-alt[]
    latestReleaseUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]

    # icon:dot-circle[] icon:file-alt[]
    issueTrackerUrlFormat: pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/issues]
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# Repo in which the release will be created.
# icon:exclamation-triangle[]
[release.gitlab]
  # Disables or enables publication to Gitea.
  # defaults to `true`.
  # icon:dot-circle[]
  enabled = true

  # Defines the connection timeout in seconds.
  # Defaults to `20`.
  # icon:dot-circle[]
  connectTimeout = 20

  # Defines the read timeout in seconds.
  # Defaults to `60`.
  # icon:dot-circle[]
  readTimeout = 60

  # The user or organization that owns the repository.
  # icon:exclamation-triangle[]
  owner = "duke"

  # The name of the repository.
  # If unspecified, will use ${project.name}.
  # icon:dot-circle[]
  name = "app"

  # The GitLab host url.
  # Defaults to `gitlab.com`.
  # icon:exclamation-triangle[]
  host = "gitlab.com"

  # Username used for authoring commits. Must have write access to the repository.
  # icon:exclamation-triangle[]
  username = "duke"

  # Password or OAuth token with write access to the repository.
  # If left unspecified, the `JRELEASER_GITLAB_TOKEN`
  # environment variable must be defined.
  # icon:exclamation-triangle[] icon:eye-slash[]
  token = "__DO_NOT_SET_HERE__"

  # The tag associated with the release.
  # May define a `JRELEASER_TAG_NAME` environment variable instead.
  # If left unspecified, will use `v{{projectVersion}}`.
  # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
  tagName = "v1.0.0"

  # The name of the release.
  # If left unspecified, will use `Release {{tagName}}`.
  # May define a `JRELEASER_RELEASE_NAME` environment variable instead.
  # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
  releaseName = "Release v1.0.0"

  # Drops and creates an existing release with matching tag.
  # May define a `JRELEASER_OVERWRITE` environment variable instead.
  # Defaults to `false`.
  # icon:dot-circle[] icon:eye-slash[]
  overwrit = true

  # Appends artifacts to an existing release with matching tag,
  # useful if `overwrite` is set to `false`.
  # May define a `JRELEASER_UPDATE` environment variable instead.
  # Defaults to `false`.
  # icon:dot-circle[] icon:eye-slash[]
  update = true

  # Skips creating a tag.
  # Useful when the tag was created externally.
  # May define a `JRELEASER_SKIP_TAG` environment variable instead.
  # Defaults to `false`.
  # icon:dot-circle[] icon:eye-slash[]
  skipTag = false

  # The GitLab API endpoint to use.
  # You can skip `/api/v4` as it will be added by default.
  # Defaults to `pass:[https://gitlab.com]`.
  # icon:dot-circle[]
  apiEndpoint = "pass:[https://gitlab.com]"

  # Git author used to commit to the repository.

  # Name used when authoring commits.
  # Defaults to `jreleaserbot`.
  # icon:dot-circle[]
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # Defaults to `pass:[jreleaser@kordamp.org]`.
  # icon:dot-circle[]
  commitAuthor.email = "pass:[jreleaser@kordamp.org]"

  # Signs commits with the configured credentials.
  # The xref:configuration:signing.adoc[] section must be configured as well.
  # Defaults to `false`.
  # icon:dot-circle[]
  sign = false

  # Changelog customization.

  # Disables or enables the changelog.
  # defaults to `true`.
  # icon:dot-circle[]
  changelog.enabled = true

  # Sorts commits in ascending (oldest first) or descending (newer first).
  # Valid values are: `ASC`, `DESC`.
  # Defaults to `DESC`.
  # icon:dot-circle[]
  changelog.sort = "DESC"

  # Path to an external file that contains the changelog, read as is.
  # May be a relative path to the configuration file or an absolute path.
  # If unspecified, JReleaser will automatically calculate the changelog.
  # icon:dot-circle[]
  changelog.external = "path/to/changelog.md"

  # Create explicit markdown links for commit hashes.
  # Defaults to `false`.
  # icon:dot-circle[]
  changelog.links = false

  # Enables or disables formatting options.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # icon:dot-circle[]
  changelog.formatted = "ALWAYS"

  # The template to use for each change.
  # Defaults to `- {{commitShortHash}} {{commitTitle}} ({{commitAuthor}})`.
  # icon:dot-circle[] icon:file-alt[]
  changelog.change = "- {{commitShortHash}} {{commitTitle}}"

  # The template to use for the whole changelog.
  # Defaults is shown.
  # icon:dot-circle[] icon:file-alt[]
  changelog.content = """
    # Changelog

    {{changelogChanges}
    {{changelogContributors}}"""

  # Path to a template file that defines the contents.
  # Review the available xref:configuration:name-templates.adoc[].
  # Defaults to `src/jreleaser/templates/changelog.tpl`.
  # icon:dot-circle[]
  changelog.contentTemplate = "path/to/template/changelog.tpl"

  # Hide uncategorized commits.
  # Defaults to `false`.
  # icon:dot-circle[]
  changelog.hideUncategorized = true

  # A list of labels to be included.
  # Only changes matching this list will be included.
  # Defaults to empty.
  # icon:dot-circle[]
  changelog.includeLabels = ["issue"]

  # A list of labels to be excluded.
  # Changes matching this list will be excluded.
  # Defaults to empty.
  # icon:dot-circle[]
  changelog.excludeLabels = ["issue"]

  # Defines rules that apply labels to changes.
  # Matchers are evaluated independently; the label will
  # be set if at least one of the matchers meets the criteria.
  # icon:dot-circle[]
  pass:[[[release.gitlab.changelog.labelers]]]
    # The label to be applied.
    # icon:exclamation-triangle[]
    label = "issue"

    # Matches the text of the first commit line.
    # icon:dot-circle[]
    title = "^fix:"

    # Matches the full text of the commit.
    # icon:dot-circle[]
    body = "Fixes #"

  # Groups changes by category.
  # Defaults are shown.
  # icon:dot-circle[]
  pass:[[[release.gitlab.changelog.categories]]]
    title = "🚀 Features"
    labels = ["feature", "enhancement"]

  pass:[[[release.gitlab.changelog.categories]]]
    title = "🐛 Bug Fixes"
    labels = ["bug", "fix"]

  # Defines rules for replacing the generated content.
  # Each replacer is applied in order.
  # icon:dot-circle[]
  pass:[[[release.gitlab.changelog.replacers]]]
    search = "\[chore\]\s"
    replace = ""

  pass:[[[release.gitlab.changelog.replacers]]]
    search = "/CVE-(\d{4})-(\d+)/g"
    replace = "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2"

  # A milestone associated with the release

  # Close the milestone (if it exists and still open) upon release.
  # Defaults to `true`.
  # icon:dot-circle[]
  milestone.close = true

  # The name/title of the milestone.
  # May define a `JRELEASER_MILESTONE_NAME` environment variable instead.
  # Defaults to `{{tagName}}`.
  # icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
  milestone.name = "{{tagName}}"

  # The target branch to use.
  # May define a `JRELEASER_BRANCH` environment variable instead.
  # Defaults to the branch pointed by HEAD.
  # icon:dot-circle[] icon:eye-slash[]
  branch = "main"

  # The following properties define icon:dot-circle[] URL formats.
  # Defaults are shown.
  # Review the available xref:configuration:name-templates.adoc[].

  # icon:dot-circle[] icon:file-alt[]
  repoUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}]"

  # icon:dot-circle[] icon:file-alt[]
  repoCloneUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}.git]"

  # icon:dot-circle[] icon:file-alt[]
  commitUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/commits]"

  # icon:dot-circle[] icon:file-alt[]
  downloadUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}/downloads/{{artifactFileName}}]"

  # icon:dot-circle[] icon:file-alt[]
  releaseNotesUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]"

  # icon:dot-circle[] icon:file-alt[]
  latestReleaseUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]"

  # icon:dot-circle[] icon:file-alt[]
  issueTrackerUrlFormat = "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/issues]"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:exclamation-triangle[]
  "release": {
    // Repo in which the release will be created.
    // icon:exclamation-triangle[]
    "gitlab": {
      // Disables or enables publication to GitLab.
      // defaults to `true`.
      // icon:dot-circle[]
      "enabled": true,

      // Defines the connection timeout in seconds.
      // Defaults to `20`.
      // icon:dot-circle[]
      "connectTimeout": 20,

      // Defines the read timeout in seconds.
      // Defaults to `60`.
      // icon:dot-circle[]
      "readTimeout": 60,

      // The user or organization that owns the repository.
      // If unspecified, will read it from the 'origin' git remote.
      // icon:dot-circle[]
      "owner": "duke",

      // The name of the repository.
      // If unspecified, will read it from the 'origin' git remote.
      // icon:dot-circle[]
      "name": "app",

      // The GitLab host url.
      // Defaults to `gitlab.com`.
      // icon:exclamation-triangle[]
      "host": "gitlab.com",

      // Username used for authoring commits. Must have write access to the repository.
      // icon:exclamation-triangle[]
      "username": "duke",

      // Password or OAuth token with write access to the repository.
      // If left unspecified, the `JRELEASER_GITLAB_TOKEN`
      // environment variable must be defined.
      // icon:exclamation-triangle[] icon:eye-slash[]
      "token": "__DO_NOT_SET_HERE__",

      // The tag associated with the release.
      // May define a `JRELEASER_TAG_NAME` environment variable instead.
      // If left unspecified, will use `v{{projectVersion}}`.
      // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      "tagName": "v1.0.0",

      // The name of the release.
      // May define a `JRELEASER_RELEASE_NAME` environment variable instead.
      // If left unspecified, will use `Release {{tagName}}`.
      // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      "releaseName": "Release v1.0.0",

      // Drops and creates an existing release with matching tag.
      // May define a `JRELEASER_OVERWRITE` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      "overwrite": true,

      // Appends artifacts to an existing release with matching tag,
      // useful if `overwrite` is set to `false`.
      // May define a `JRELEASER_UPDATE` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      "update": true,

      // Skips creating a tag.
      // Useful when the tag was created externally.
      // May define a `JRELEASER_SKIP_TAG` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      "skipTag": false,

      // The GitLab API endpoint to use.
      // You can skip `/api/v4` as it will be added by default.
      // Defaults to `pass:[https://gitlab.com]`.
      // icon:dot-circle[]
      "apiEndpoint": "pass:[https://gitlab.com]",

      // Git author used to commit to the repository.
      // icon:dot-circle[]
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // icon:dot-circle[]
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `pass:[jreleaser@kordamp.org]`.
        // icon:dot-circle[]
        "email": "pass:[jreleaser@kordamp.org]"
      },

      // Signs commits with the configured credentials.
      // The xref:configuration:signing.adoc[] section must be configured as well.
      // Defaults to `false`.
      // icon:dot-circle[]
      "sign": false,

      // Changelog customization.
      // icon:dot-circle[]
      "changelog": {
        // Disables or enables the changelog.
        // defaults to `true`.
        // icon:dot-circle[]
        "enabled": true,

        // Sorts commits in ascending (oldest first) or descending (newer first).
        // Valid values are: `ASC`, `DESC`.
        // Defaults to `DESC`.
        // icon:dot-circle[]
        "sort": "DESC",

        // Path to an external file that contains the changelog, read as is.
        // May be a relative path to the configuration file or an absolute path.
        // If unspecified, JReleaser will automatically calculate the changelog.
        // icon:dot-circle[]
        "external": "path/to/changelog.md",

        // Create explicit markdown links for commit hashes.
        // Defaults to `false`.
        // icon:dot-circle[]
        "links": false,

        // Enables or disables formatting options.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `NEVER`.
        // icon:dot-circle[]
        "formatted": "ALWAYS",

        // The template to use for each change.
        // Defaults to `- {{commitShortHash}} {{commitTitle}} ({{commitAuthor}})`.
        // icon:dot-circle[] icon:file-alt[]
        "change": "- {{commitShortHash}} {{commitTitle}}",

        // The template to use for the whole changelog.
        // Defaults is shown.
        // icon:dot-circle[] icon:file-alt[]
        "content": "#Changelog\n\n{{changelogChanges}}\n{{changelogContributors}}",

        // Path to a template file that defines the contents.
        // Review the available xref:configuration:name-templates.adoc[].
        // Defaults to `src/jreleaser/templates/changelog.tpl`.
        // icon:dot-circle[]
        "contentTemplate": "path/to/template/changelog.tpl",

        // Hide uncategorized commits.
        // Defaults to `false`.
        // icon:dot-circle[]
        "hideUncategorized": true,

        // A list of labels to be included.
        // Only changes matching this list will be included.
        // Defaults to empty.
        // icon:dot-circle[]
        "includeLabels": [
           "issue"
        ],

        // A list of labels to be excluded.
        // Changes matching this list will be excluded.
        // Defaults to empty.
        // icon:dot-circle[]
        "excludeLabels": [
           "issue"
        ],

        // Defines rules that apply labels to changes.
        // Matchers are evaluated independently; the label will
        // be set if at least one of the matchers meets the criteria.
        // icon:dot-circle[]
        "labelers": [
          {
            // The label to be applied.
            // icon:exclamation-triangle[]
            "label": "issue",

            // Matches the text of the first commit line.
            // icon:dot-circle[]
            "title": "^fix:",

            // Matches the full text of the commit.
            // icon:dot-circle[]
            "body": "Fixes #"
          }
        ],

        // Groups changes by category.
        // Defaults are shown.
        // icon:dot-circle[]
        "categories": [
          {
            "title": "🚀 Features",
            "labels": [
              "feature",
              "enhancement"
            ]
          },
          {
            "title": "🐛 Bug Fixes",
            "labels": [
              "bug",
              "fix"
            ]
          }
        ],

        // Defines rules for replacing the generated content.
        // Each replacer is applied in order.
        // icon:dot-circle[]
        "replacers": [
          {
            "search": "\[chore\]\s",
            "replace": ""
          },
          {
            "search": "/CVE-(\d{4})-(\d+)/g",
            "replace": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2"
          }
        ]
      },

      // A milestone associated with the release
      // icon:dot-circle[]
      "milestone": {
        // Close the milestone (if it exists and still open) upon release.
        // Defaults to `true`.
        // icon:dot-circle[]
        "close": true,

        // The name/title of the milestone.
        // May define a `JRELEASER_MILESTONE_NAME` environment variable instead.
        // Defaults to `{{tagName}}`.
        // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
        "name": "{{tagName}}"
      },

      // The target branch to use.
      // May define a `JRELEASER_BRANCH` environment variable instead.
      // Defaults to the branch pointed by HEAD.
      // icon:dot-circle[] icon:eye-slash[]
      "branch": "main",

      // The following properties define icon:dot-circle[] URL formats.
      // Defaults are shown.
      // Review the available xref:configuration:name-templates.adoc[].

      // icon:dot-circle[] icon:file-alt[]
      "repoUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}]",

      // icon:dot-circle[] icon:file-alt[]
      "repoCloneUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}.git]",

      // icon:dot-circle[] icon:file-alt[]
      "commitUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/commits]",

      // icon:dot-circle[] icon:file-alt[]
      "downloadUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}/downloads/{{artifactFileName}}]",

      // icon:dot-circle[] icon:file-alt[]
      "releaseNotesUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]",

      // icon:dot-circle[] icon:file-alt[]
      "latestReleaseUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]",

      // icon:dot-circle[] icon:file-alt[]
      "issueTrackerUrlFormat": "pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/issues]"
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:exclamation-triangle[]
  -->
  <release>
    <!--
      Repo in which the release will be created.
      icon:exclamation-triangle[]
    -->
    <gitlab>

      <!--
        Disables or enables publication to GitLab.
        defaults to `true`.
        icon:dot-circle[]
      -->
      <enabled>true</enabled>

      <!--
        Defines the connection timeout in seconds.
        Defaults to `20`.
        icon:dot-circle[]
      -->
      <connectTimeout>20</connectTimeout>

      <!--
        Defines the read timeout in seconds.
        Defaults to `60`.
        icon:dot-circle[]
      -->
      <readTimeout>60</readTimeout>

      <!--
        The user or organization that owns the repository.
        If unspecified, will read it from the 'origin' git remote.
        icon:dot-circle[]
      -->
      <owner>duke</owner>

      <!--
        The name of the repository.
        If unspecified, will read it from the 'origin' git remote.
        icon:dot-circle[]
      -->
      <name>app</name>

      <!--
        The GitLab host url.
        Defaults to `gitlab.com`.
        icon:exclamation-triangle[]
      -->
      <host>gitlab.com</host>

      <!--
        Username used for authoring commits. Must have write access to the repository.
        icon:exclamation-triangle[]
      -->
      <username>duke</username>

      <!--
        Password or OAuth token with write access to the repository.
        If left unspecified, the `JRELEASER_GITLAB_TOKEN` 
        environment variable must be defined.
        icon:exclamation-triangle[] icon:eye-slash[]
      -->
      <token>__DO_NOT_SET_HERE__</token>

      <!--
        The tag associated with the release.
        May define a `JRELEASER_TAG_NAME` environment variable instead.
        If left unspecified, will use `v{{projectVersion}}`.
        icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      -->
      <tagName>v1.0.0</tagName>

      <!--
        The name of the release.
        May define a `JRELEASER_RELEASE_NAME` environment variable instead.
        If left unspecified, will use `Release {{tagName}}`.
        icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      -->
      <releaseName>Release v1.0.0</releaseName>

      <!--
        Drops and creates an existing release with matching tag.
        May define a `JRELEASER_OVERWRITE` environment variable instead.
        Defaults to `false`.
        icon:dot-circle[] icon:eye-slash[]
      -->
      <overwrite>true</overwrite>

      <!--
        Appends artifacts to an existing release with matching tag,
        useful if `overwrite` is set to `false`.
        May define a `JRELEASER_UPDATE` environment variable instead.
        Defaults to `false`.
        icon:dot-circle[] icon:eye-slash[]
      -->
      <update>true</update>

      <!--
        Skips creating a tag.
        Useful when the tag was created externally.
        May define a `JRELEASER_SKIP_TAG` environment variable instead.
        Defaults to `false`.
        icon:dot-circle[] icon:eye-slash[]
      -->
      <skipTag>false</skipTag>

      <!--
        The GitLab API endpoint to use.
        You can skip `/api/v4` as it will be added by default.
        Defaults to `pass:[https://gitlab.com]`.
        icon:dot-circle[]
      -->
      <apiEndpoint>pass:[https://gitlab.com]</apiEndpoint>

      <!--
        Git author used to commit to the repository.
        icon:dot-circle[]
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          icon:dot-circle[]
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `pass:[jreleaser@kordamp.org]`.
          icon:dot-circle[]
        -->
        <email>pass:[jreleaser@kordamp.org]</email>
      </commitAuthor>

      <!--
        Signs commits with the configured credentials.
        The xref:configuration:signing.adoc[] section must be configured as well.
        Defaults to `false`.
        icon:dot-circle[]
      -->
      <sign>false</sign>

      <!--
        Changelog customization.
        icon:dot-circle[]
      -->
      <changelog>

        <!--
           Disables or enables the changelog.
          defaults to `true`.
          icon:dot-circle[]
        -->
        <enabled>true</enabled>

        <!--
          Sorts commits in ascending (oldest first) or descending (newer first).
          Valid values are>`ASC`, `DESC`.
          Defaults to `DESC`.
          icon:dot-circle[]
        -->
        <sort>DESC</sort>

        <!--
          Path to an external file that contains the changelog, read as is.
          May be a relative path to the configuration file or an absolute path.
          If unspecified, JReleaser will automatically calculate the changelog.
          icon:dot-circle[]
        -->
        <external>path/to/changelog.md</external>

        <!--
          Create explicit markdown links for commit hashes.
          Defaults to `false`.
          icon:dot-circle[]
        -->
        <links>false</links>

        <!--
          Enables or disables formatting options.
          Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `NEVER`.
          icon:dot-circle[]
        -->
        <formatted>ALWAYS</formatted>

        <!--
          The template to use for each change.
          Defaults to `- {{commitShortHash}} {{commitTitle}} ({{commitAuthor}})`.
          icon:dot-circle[] icon:file-alt[]
        -->
        <change>- {{commitShortHash}} {{commitTitle}}</change>

        <!--
          The template to use for the whole changelog.
          Defaults is shown.
          icon:dot-circle[] icon:file-alt[]
        -->
        <content>
          # Changelog

          {{changelogChanges}
          {{changelogContributors}}
        </content>

        <!--
          Path to a template file that defines the contents.
          Review the available xref:configuration:name-templates.adoc[].
          Defaults to `src/jreleaser/templates/changelog.tpl`.
          icon:dot-circle[]
        -->
        <contentTemplate>path/to/template/changelog.tpl</contentTemplate>

        <!--
          Hide uncategorized commits.
          Defaults to `false`.
          icon:dot-circle[]
        -->
        <hideUncategorized>true</hideUncategorized>

        <!--
          A list of labels to be included.
          Only changes matching this list will be included.
          Defaults to empty.
          icon:dot-circle[]
        -->
        <includeLabels>
          <includeLabel>issue</includeLabel>
        </includeLabels>

        <!--
          A list of labels to be excluded.
          Changes matching this list will be excluded.
          Defaults to empty.
          icon:dot-circle[]
        -->
        <excludeLabels>
          <excludeLabel>issue</excludeLabel>
        </excludeLabels>

        <!--
          Defines rules that apply labels to changes.
          Matchers are evaluated independently; the label will
          be set if at least one of the matchers meets the criteria.
          icon:dot-circle[]
        -->
        <labelers>
          <labeler>
            <!--
              The label to be applied.
              icon:exclamation-triangle[]
            -->
            <label>issue</label>

            <!--
              Matches the text of the first commit line.
              icon:dot-circle[]
            -->
            <title>^fix:</title>

            <!--
              Matches the full text of the commit.
              icon:dot-circle[]
            -->
            <body>Fixes #</body>
          </labeler>
        </labelers>

        <!--
          Groups changes by category.
          Defaults are shown.
          icon:dot-circle[]
        -->
        <categories>
          <category>
            <title>🚀 Features</title>
            <labelsAsString>feature,enhancement</labelsAsString>
          </category>
          <category>
            <title>🐛 Bug Fixes</title>
            <labelsAsString>bug,fix</labelsAsString>
          </category>
        </categories>

        <!--
          Defines rules for replacing the generated content.
          Each replacer is applied in order.
          icon:dot-circle[]
        -->
        <replacers>
          <replacer>
            <search>\[chore\]\s</search>
          </replacer>
          <replacer>
            <search>/CVE-(\d{4})-(\d+)/g</search>
            <replace>https: cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2</replace>
          </replacer>
        </replacers>
      </changelog>

      <!--
        A milestone associated with the release
        icon:dot-circle[]
      -->
      <milestone>

        <!--
          Close the milestone (if it exists and still open) upon release.
          Defaults to `true`.
          icon:dot-circle[]
         -->
        <close>true</close>

        <!--
          The name/title of the milestone.
          May define a `JRELEASER_MILESTONE_NAME` environment variable instead.
          Defaults to `{{tagName}}`.
          icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
         -->
        <name>{{tagName}}</name>
      </milestone>
      <!--
        The target branch to use.
        May define a `JRELEASER_BRANCH` environment variable instead.
        Defaults to the branch pointed by HEAD.
        icon:dot-circle[] icon:eye-slash[]
      -->
      <branch>main</branch>

      <!--
        The following properties define icon:dot-circle[] URL formats.
        Defaults are shown.
        Review the available xref:configuration:name-templates.adoc[].
      -->

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <repoUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}]</repoUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <repoCloneUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}.git]</repoCloneUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <commitUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/commits]</commitUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <downloadUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}/downloads/{{artifactFileName}}]</downloadUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <releaseNotesUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]</releaseNotesUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <latestReleaseUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]</latestReleaseUrlFormat>

      <!--
        icon:dot-circle[] icon:file-alt[]
      -->
      <issueTrackerUrlFormat>pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/issues]</issueTrackerUrlFormat>
    </gitlab>
  </release>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:exclamation-triangle[]
  release {
    // Repo in which the release will be created.
    // icon:exclamation-triangle[]
    gitlab {
      // Disables or enables publication to GitLab.
      // defaults to `true`.
      // icon:dot-circle[]
      enabled = true

      // Defines the connection timeout in seconds.
      // Defaults to `20`.
      // icon:dot-circle[]
      connectTimeout = 20

      // Defines the read timeout in seconds.
      // Defaults to `60`.
      // icon:dot-circle[]
      readTimeout = 60

      // The user or organization that owns the repository.
      // If unspecified, will read it from the 'origin' git remote.
      // icon:dot-circle[]
      owner = 'duke'

      // The name of the repository.
      // If unspecified, will read it from the 'origin' git remote.
      // icon:dot-circle[]
      name = 'app'

      // The GitLab host url.
      // Defaults to `gitlab.com`.
      // icon:exclamation-triangle[]
      host = 'gitlab.com'

      // Username used for authoring commits. Must have write access to the repository.
      // icon:exclamation-triangle[]
      username = 'duke'

      // Password or OAuth token with write access to the repository.
      // If left unspecified, the `JRELEASER_GITLAB_TOKEN`
      // environment variable must be defined.
      // icon:exclamation-triangle[] icon:eye-slash[]
      token = '__DO_NOT_SET_HERE__'

      // The tag associated with the release.
      // May define a `JRELEASER_TAG_NAME` environment variable instead.
      // If left unspecified, will use `v{{projectVersion}}`.
      // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      tagName = 'v1.0.0'

      // The name of the release.
      // May define a `JRELEASER_RELEASE_NAME` environment variable instead.
      // If left unspecified, will use `Release {{tagName}}`.
      // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
      releaseName = 'Release v1.0.0'

      // Drops and creates an existing release with matching tag.
      // May define a `JRELEASER_OVERWRITE` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      overwrite = true

      // Appends artifacts to an existing release with matching tag,
      // useful if `overwrite` is set to `false`.
      // May define a `JRELEASER_UPDATE` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      update = true

      // Skips creating a tag.
      // Useful when the tag was created externally.
      // May define a `JRELEASER_SKIP_TAG` environment variable instead.
      // Defaults to `false`.
      // icon:dot-circle[] icon:eye-slash[]
      skipTag = false

      // The GitLab API endpoint to use.
      // You can skip `/api/v4` as it will be added by default.
      // Defaults to `pass:[https://gitlab.com]`.
      // icon:dot-circle[]
      apiEndpoint = 'pass:[https://gitlab.com]'

      // Git author used to commit to the repository.
      // icon:dot-circle[]
      commitAuthor {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // icon:dot-circle[]
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // Defaults to `pass:[jreleaser@kordamp.org]`.
        // icon:dot-circle[]
        email = 'pass:[jreleaser@kordamp.org]'
      }

      // Signs commits with the configured credentials.
      // The xref:configuration:signing.adoc[] section must be configured as well.
      // Defaults to `false`.
      // icon:dot-circle[]
      sign = false

      // Changelog customization.
      // icon:dot-circle[]
      changelog {
        // Disables or enables the changelog.
        // defaults to `true`.
        // icon:dot-circle[]
        enabled = true

        // Sorts commits in ascending (oldest first) or descending (newer first).
        // Valid values are = `ASC`, `DESC`.
        // Defaults to `DESC`.
        // icon:dot-circle[]
        sort = 'DESC'

        // Path to an external file that contains the changelog, read as is.
        // May be a relative path to the configuration file or an absolute path.
        // If unspecified, JReleaser will automatically calculate the changelog.
        // icon:dot-circle[]
        external = 'path/to/changelog.md'

        // Create explicit markdown links for commit hashes.
        // Defaults to `false`.
        // icon:dot-circle[]
        links = false

        // Enables or disables formatting options.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `NEVER`.
        // icon:dot-circle[]
        formatted = 'ALWAYS'

        // The template to use for each change.
        // Defaults to `- {{commitShortHash}} {{commitTitle}} ({{commitAuthor}})`.
        // icon:dot-circle[] icon:file-alt[]
        change = '- {{commitShortHash}} {{commitTitle}}'

        // The template to use for the whole changelog.
        // Defaults is shown.
        // icon:dot-circle[] icon:file-alt[]
        content = '#Changelog\n\n{{changelogChanges}}\n{{changelogContributors}}'

        // Path to a template file that defines the contents.
        // Review the available xref:configuration:name-templates.adoc[].
        // Defaults to `src/jreleaser/templates/changelog.tpl`.
        // icon:dot-circle[]
        contentTemplate = 'path/to/template/changelog.tpl'

        // Hide uncategorized commits.
        // Defaults to `false`.
        // icon:dot-circle[]
        hideUncategorized = true

        // A list of labels to be included.
        // Only changes matching this list will be included.
        // Defaults to empty.
        // icon:dot-circle[]
        includeLabels = [
           'issue'
        ]

        // A list of labels to be excluded.
        // Changes matching this list will be excluded.
        // Defaults to empty.
        // icon:dot-circle[]
        excludeLabels = [
           'issue'
        ]

        // Defines rules that apply labels to changes.
        // Matchers are evaluated independently; the label will
        // be set if at least one of the matchers meets the criteria.
        // icon:dot-circle[]
        labeler {
          // The label to be applied.
          // icon:exclamation-triangle[]
          label = 'issue'

          // Matches the text of the first commit line.
          // icon:dot-circle[]
          title = '^fix:'

          // Matches the full text of the commit.
          // icon:dot-circle[]
          body = 'Fixes #'
        }

        // Groups changes by category.
        // Defaults are shown.
        // icon:dot-circle[]
        category  {
          title = '🚀 Features'
          labels = [
            'feature',
            'enhancement'
          ]
        }
        category {
          title = '🐛 Bug Fixes'
          labels = [
            'bug',
            'fix'
          ]
        }

        // Defines rules for replacing the generated content.
        // Each replacer is applied in order.
        // icon:dot-circle[]
        replacer {
          search = '\[chore\]\s'
          replace = ''
        }
        replacer {
          search = '/CVE-(\d{4})-(\d+)/g'
          replace = 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2'
        }
      }

      // A milestone associated with the release
      // icon:dot-circle[]
      milestone {
        // Close the milestone (if it exists and still active) upon release.
        // Defaults to `true`.
        // icon:dot-circle[]
        close = true

        // The name/title of the milestone.
        // May define a `JRELEASER_MILESTONE_NAME` environment variable instead.
        // Defaults to `{{tagName}}`.
        // icon:dot-circle[] icon:eye-slash[] icon:file-alt[]
        name = '{{tagName}}'
      }

      // The target branch to use.
      // May define a `JRELEASER_BRANCH` environment variable instead.
      // Defaults to the branch pointed by HEAD.
      // icon:dot-circle[] icon:eye-slash[]
      branch = 'main'

      // The following properties define icon:dot-circle[] URL formats.
      // Defaults are shown.
      // Review the available xref:configuration:name-templates.adoc[].

      // icon:dot-circle[] icon:file-alt[]
      repoUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}]'

      // icon:dot-circle[] icon:file-alt[]
      repoCloneUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}.git]'

      // icon:dot-circle[] icon:file-alt[]
      commitUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/commits]'

      // icon:dot-circle[] icon:file-alt[]
      downloadUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}/downloads/{{artifactFileName}}]'

      // icon:dot-circle[] icon:file-alt[]
      releaseNotesUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]'

      // icon:dot-circle[] icon:file-alt[]
      latestReleaseUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/releases/{{tagName}}]'

      // icon:dot-circle[] icon:file-alt[]
      issueTrackerUrlFormat = 'pass:[https://{{repoHost}}/{{repoOwner}}/{{repoName}}/-/issues]'
}
----
====

== Changelog

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

Changelog format applies only to the automatically generated changelog, that is, formatting wo'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 `change` property only accepts the following name templates:

[%header, cols="<2,<5", width="100%"]
|===
| 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 xref:configuration:name-templates.adoc[], take special consideration on
`{{changelogChanges}}` and `{{changelogContributors}}` as they define the parsed commits.

The following configuration

image::ROOT:jreleaser-changelog-config.jpg[]

Generates a changelog similar to

image::ROOT:jreleaser-changelog-render.jpg[]