Skip to main content

GitLab Integration 🦊

note

If you have built from source, enable the gitlab feature flag for the integration to work.

For projects hosted on GitLab, you can use git-cliff to add the following to your changelog:

  • GitLab usernames
  • Contributors list (all contributors / first time)
  • Pull request links (associated with the commits)

Setting up the remote​

As default, remote upstream URL is automatically retrieved from the Git repository.

If that doesn't work or if you want to set a custom remote, there are a couple of ways of doing it:

[remote.gitlab]
owner = "orhun"
repo = "git-cliff"
token = "***"

  • Use the --gitlab-repo argument (takes values in OWNER/REPO format, e.g. "orhun/git-cliff")

  • Use the GITLAB_REPO environment variable (same format as --gitlab-repo)

Authentication​

tip

GitLab REST API is being used to retrieve data from GitLab and it has rate limiting rules.

You can follow this guide for creating an access token.

To set an access token, you can use the configuration file (not recommended), --gitlab-token argument or GITLAB_TOKEN environment variable.

For example:

GITLAB_TOKEN="***" git cliff --gitlab-repo "orhun/git-cliff"
tip

You can use the GITLAB_API_URL environment variable want to override the API URL. This is useful if you are using your own GitLab instance.

When your project on your own GitLab has one or many subgroups (e.g my.gitlab.com/myGroup/mySubgroup/myProject) you don't need to URL encode the owner in the configuration. (i.e. simply use "myGroup/mySubgroup")

info

If you are getting invalid peer certificate errors, you can use the --use-native-tls flag to load certificates from the platform's native certificate store.

It is also possible to configure this in the configuration file, see the remote configuration for more information.

Templating​

tip

See the templating documentation for general information about how the template engine works.

Remote​

You can use the following context for adding the remote to the changelog:

{
  "gitlab": {
    "owner": "orhun",
    "repo": "git-cliff"
  }
}

For example:

https://gitlab.com/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}/-/tags/{{ version }}
tip

If you are using GitLab CI, you can use CI_PROJECT_URL environment variable instead:

{{ get_env(name="CI_PROJECT_URL") }}/-/tags/{{ version }}

Commit authors​

For each commit, GitLab related values are added as a nested object (named remote) to the template context:

{
  "id": "8edec7fd50f703811d55f14a3c5f0fd02b43d9e7",
  "message": "refactor(config): remove unnecessary newline from configs\n",
  "group": "🚜 Refactor",

  "...": "<strip>",

  "remote": {
    "username": "orhun",
    "pr_author": "orhun",
    "pr_title": "some things have changed",
    "pr_number": 420,
    "pr_labels": ["rust"],
    "is_first_time": false
  }
}

This can be used in the template as follows:

{% for commit in commits %}
  * {{ commit.message | split(pat="\n") | first | trim }}\
    {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif %}\
    {% if commit.remote.pr_number %} in #{{ commit.remote.pr_number }}{%- endif %}
{%- endfor -%}

The will result in:

- feat(commit): add merge_commit flag to the context by @orhun in #389
- feat(args): set `CHANGELOG.md` as default missing value for output option by @sh-cho in #354

username is resolved from the commit author, whereas pr_author is the account that opened the pull request. They can differ, so a template that wants to credit the contributor rather than whoever the commit resolves to can prefer pr_author:

{% if commit.remote.pr_author or commit.remote.username %} by @{{ commit.remote.pr_author | default(value=commit.remote.username) }}{% endif %}

The guard matters: commit.remote is absent for any commit the remote API did not return, and an unguarded lookup on it aborts the whole render.

Contributors​

For each release, following contributors data is added to the template context as a nested object:

{
  "version": "v1.4.0",
  "commits": [],
  "commit_id": "0af9eb24888d1a8c9b2887fbe5427985582a0f26",
  "timestamp": 0,
  "previous": null,
  "gitlab": {
    "contributors": [
      {
        "username": "orhun",
        "pr_title": "some things have changed",
        "pr_number": 420,
        "pr_labels": ["rust"],
        "is_first_time": true
      },
      {
        "username": "cliffjumper",
        "pr_title": "I love jumping",
        "pr_number": 999,
        "pr_labels": ["rust"],
        "is_first_time": true
      }
    ]
  }
}

This can be used in the template as follows:

{% for contributor in gitlab.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}

The will result in:

- @orhun made their first contribution in #420
- @cliffjumper made their first contribution in #999

GitLab Changelog​

If you would like to create release notes tailored for GitLab, you can use the gitlab.toml example.

Since it is already embedded into the binary, you can simply run:

git cliff -c gitlab

This will generate a changelog such as:

## What's Changed in v1.0.0

### Features

- feat(parser): add ability to parse arrays by @orhun in [!123](https://gitlab.com/orhun/git-cliff/-/merge_requests/123)

### New Contributors

- @someone made their first contribution in [!360](https://gitlab.com/orhun/git-cliff/-/merge_requests/360)

**Tag**: [v1.0.0](https://gitlab.com/orhun/git-cliff/-/tags/v1.0.0)

<!-- generated by git-cliff -->

Alternatively, you can use gitlab-keepachangelog.toml template which is a mix of GitLab and Keep a Changelog formats.

Since it is already embedded into the binary, you can simply run:

git cliff -c gitlab-keepachangelog