--- stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, api --- # Changelogs **(FREE)** Changelogs are generated based on commit titles and Git trailers. To be included in a changelog, a commit must contain a specific Git trailer. Changelogs are generated from commit titles, and categorized by Git trailer type. You can enrich changelog entries with additional data, such as a link to the merge request or details about the commit author. Changelog formats [can be customized](#customize-the-changelog-output) with a template. Each section in the default changelog has a title containing the version number and release date, like this: ````markdown ## 1.0.0 (2021-01-05) ### Features (4 changes) - [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) - [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) - [Feature 3](gitlab-org/gitlab@234abc) by @steve - [Feature 4](gitlab-org/gitlab@456) ```` The date format for sections can be customized, but the rest of the title cannot. When adding new sections, GitLab parses these titles to determine where to place the new information in the file. GitLab sorts sections according to their versions, not their dates. Each section contains changes sorted by category (like **Features**), and the format of these sections can be changed. The section names derive from the values of the Git trailer used to include or exclude commits. Commits for changelogs can be retrieved when operating on a mirror. GitLab itself uses this feature, because security releases can include changes from both public projects and private security mirrors. ## Add a trailer to a Git commit You can add trailers manually when you write a commit message. To include a commit using the default trailer of `Changelog` and categorize it as a feature, add the string `Changelog: feature` to your commit message, like this: ```plaintext Changelog: feature ``` ## Create a changelog To generate changelog data based on commits in a repository, see [Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) in the API documentation. The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). ### Reverted commits > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. To be treated as a revert commit, the commit message must contain the string `This reverts commit `, where `SHA` is the SHA of the commit to be reverted. When generating a changelog for a range, GitLab ignores commits both added and reverted in that range. In this example, commit C reverts commit B. Because commit C has no other trailer, only commit A is added to the changelog: ```mermaid graph LR A[Commit A
Changelog: changed] --> B[Commit B
Changelog: changed] B --> C[Commit C
Reverts commit B] ``` However, if the revert commit (commit C) _also_ contains a changelog trailer, both commits A and C are included in the changelog: ```mermaid graph LR A[Commit A

Changelog: changed] --> B[Commit B

Changelog: changed] B --> C[Commit C
Reverts commit B
Changelog: changed] ``` Commit B is skipped. ### Customize the changelog output To customize the changelog output, edit the changelog configuration file. The default location for this configuration is `.gitlab/changelog_config.yml`. The file supports these variables: - `date_format`: The date format, in `strftime` format, used in the title of the newly added changelog data. - `template`: A custom template to use when generating the changelog data. - `include_groups`: A list of group full paths containing users whose contributions should be credited regardless of project membership. The user generating the changelog must have access to each group for credit to be given. - `categories`: A hash that maps raw category names to the names to use in the changelog. To alter the names displayed in the changelog, add these lines to your configuration file and edit them to meet your needs. This example renders the category titles as `### Features`, `### Bug fixes`, and `### Performance improvements`: ```yaml --- categories: feature: Features bug: Bug fixes performance: Performance improvements ``` ### Custom templates Category sections are generated using a template. The default template: ```plaintext {% if categories %} {% each categories %} ### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) {% each entries %} - [{{ title }}]({{ commit.reference }})\ {% if author.credit %} by {{ author.reference }}{% end %}\ {% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} {% end %} {% end %} {% else %} No changes. {% end %} ``` The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing data. Statements must be terminated using a `{% end %}` tag. Both the `if` and `each` statements require a single argument. For example, for a variable called `valid`, you can display "yes" when this value is true, and display "nope" otherwise by doing the following: ```plaintext {% if valid %} yes {% else %} nope {% end %} ``` The use of `else` is optional. A value is considered true when it's a non-empty value or boolean `true`. Empty arrays and hashes are considered false. Looping is done using `each`, and variables inside a loop are scoped to it. Referring to the current value in a loop is done using the variable tag `{{ it }}`. Other variables read their value from the current loop value. Take this template for example: ```plaintext {% each users %} {{name}} {% end %} ``` Assuming `users` is an array of objects, each with a `name` field, this would then print the name of every user. Using variable tags, you can access nested objects. For example, `{{ users.0.name }}` prints the name of the first user in the `users` variable. If a line ends in a backslash, the next newline is ignored. This allows you to wrap code across multiple lines, without introducing unnecessary newlines in the Markdown output. Tags that use `{%` and `%}` (known as expression tags) consume the newline that directly follows them, if any. This means that this: ```plaintext --- {% if foo %} bar {% end %} --- ``` Compiles into this: ```plaintext --- bar --- ``` Instead of this: ```plaintext --- bar --- ``` You can specify a custom template in your configuration, like this: ```yaml --- template: | {% if categories %} {% each categories %} ### {{ title }} {% each entries %} - [{{ title }}]({{ commit.reference }})\ {% if author.credit %} by {{ author.reference }}{% end %} {% end %} {% end %} {% else %} No changes. {% end %} ``` When specifying the template you should use `template: |` and not `template: >`, as the latter doesn't preserve newlines in the template. ### Template data At the top level, the following variable is available: - `categories`: an array of objects, one for every changelog category. In a category, the following variables are available: - `count`: the number of entries in this category. - `entries`: the entries that belong to this category. - `single_change`: a boolean that indicates if there is only one change (`true`), or multiple changes (`false`). - `title`: the title of the category (after it has been remapped). In an entry, the following variables are available (here `foo.bar` means that `bar` is a sub-field of `foo`): - `author.contributor`: a boolean set to `true` when the author is not a project member, otherwise `false`. - `author.credit`: a boolean set to `true` when `author.contributor` is `true` or when `include_groups` is configured, and the author is a member of one of the groups. - `author.reference`: a reference to the commit author (for example, `@alice`). - `commit.reference`: a reference to the commit, for example, `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. - `commit.trailers`: an object containing all the Git trailers that were present in the commit body. - `merge_request.reference`: a reference to the merge request that first introduced the change (for example, `gitlab-org/gitlab!50063`). - `title`: the title of the changelog entry (this is the commit title). The `author` and `merge_request` objects might not be present if the data couldn't be determined. For example, when a commit is created without a corresponding merge request, no merge request is displayed. ### Customize the tag format when extracting versions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. GitLab uses a regular expression (using the [re2](https://github.com/google/re2/) engine and syntax) to extract a semantic version from tag names. The default regular expression is: ```plaintext ^v?(?P0|[1-9]\d*)\.(?P0|[1-9]\d*)\.(?P0|[1-9]\d*)(?:-(?P
(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
```

This regular expression is based on the official
[semantic versioning](https://semver.org/) regular expression, and also includes
support for tag names that start with the letter `v`.

If your project uses a different format for tags, you can specify a different
regular expression. The regular expression used _must_ produce the following
capture groups. If any of these capture groups are missing, the tag is ignored:

- `major`
- `minor`
- `patch`

The following capture groups are optional:

- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate
  tags and other pre-release tags are not considered when determining the range of
  commits to generate a changelog for.
- `meta`: Optional. Specifies build metadata.

Using this information, GitLab builds a map of Git tags and their release
versions. It then determines what the latest tag is, based on the version
extracted from each tag.

To specify a custom regular expression, use the `tag_regex` setting in your
changelog configuration YAML file. For example, this pattern matches tag names
such as `version-1.2.3` but not `version-1.2`.

```yaml
---
tag_regex: '^version-(?P\d+)\.(?P\d+)\.(?P\d+)$'
```

To test if your regular expression is working, you can use websites such as
[regex101](https://regex101.com/). If the regular expression syntax is invalid,
an error is produced when generating a changelog.

## Related topics

- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API
- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab