Hugo with git-cliff on GitLab pages

[joergklein]

I have a website that I run using Hugo and is hosted on GitLab pages. The changelog is displayed using the artifacts. Unfortunately, no links to the corresponding files are displayed in GitLab. A CHANGELOG.md is not created in the root directory of the repository. Please take a look at the screenshot.

I have created a .gilab-ci.yml with the following content.

#
# Before using this .gitlab-ci.yml:
#
# - This example uses the latest Docker image, but you might want to use the
#   exact version to avoid any broken pipelines.
#   All available Hugo versions are listed under https://gitlab.com/pages/hugo/container_registry.
# - Read about the difference between hugo and hugo_extended
#   https://gitlab.com/pages/hugo/-/blob/main/README.md#hugo-vs-hugo_extended.
#   If you don't know what to use, better use the extended version.
# - To change the theme, see
#   https://gitlab.com/pages/hugo/-/blob/main/README.md#use-a-custom-theme.
#

image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
  HUGO_ENV: production
  DART_SASS_VERSION: 1.77.2
  PAGEFIND_VERSION: v1.1.0
  GIT_STRATEGY: clone # clone entire repo instead of reusing workspace
  GIT_DEPTH: 0 # avoid shallow clone to give cliff all the info it need

before_script:
  # Install curl, go git-cliff
  - apk add --no-cache curl go git-cliff
  # Install Dart Sass
  - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
  - tar -zxvf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
  - cp -r dart-sass/ /usr/local/bin
  - rm -rf dart-sass*
  - export PATH=/usr/local/bin/dart-sass:$PATH
  # Install Pagefind
  - curl -LJO https://github.com/CloudCannon/pagefind/releases/download/${PAGEFIND_VERSION}/pagefind-${PAGEFIND_VERSION}-x86_64-unknown-linux-musl.tar.gz
  - tar -zxvf pagefind-${PAGEFIND_VERSION}-x86_64-unknown-linux-musl.tar.gz
  - rm pagefind-${PAGEFIND_VERSION}-x86_64-unknown-linux-musl.tar.gz

stages:
  - changelog
  - test
  - deploy

changelog_job:
  stage: changelog
  script:
    - git-cliff -r . > CHANGELOG.md
  artifacts:
    paths:
      - CHANGELOG.md

test_job:
  stage: test
  script:
    - hugo --minify
  rules:
    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH

pages:
  stage: deploy
  script:
    - hugo --minify
    - ./pagefind --site "public"
    - rm pagefind
    - hugo --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
    # If you want schedule then comment out this line
    # - if: '$CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE == "schedule"'

cliff.toml

# git-cliff ~ default configuration file
# https://git-cliff.org/docs/configuration
#
# Lines starting with "#" are comments.
# Configuration options are organized into tables and keys.
# See documentation for more information on available options.

[changelog]
# changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
{% if version %}\
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
    ## [unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | striptags | trim | upper_first }}
    {% for commit in commits %}
        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
            {% if commit.breaking %}[**breaking**] {% endif %}\
            {{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\n
"""
# template for the changelog footer
footer = """
<!-- generated by git-cliff -->
"""
# remove the leading and trailing s
trim = true
# postprocessors
postprocessors = [
  { pattern = '<REPO>', replace = "https://gitlab.com/user/test" }, # replace repository URL
]
[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = false
# process each line of a commit as an individual commit
split_commits = false
# regex for preprocessing the commit messages
commit_preprocessors = [
  # Replace issue numbers
  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"},
  # Check spelling of the commit with https://github.com/crate-ci/typos
  # If the spelling is incorrect, it will be automatically fixed.
  #{ pattern = '.*', replace_command = 'typos --write-changes -' },
]
# regex for parsing and grouping commits
commit_parsers = [
  { message = "^feat", group = "<!-- 0 -->Features" },
  { message = "^fix", group = "<!-- 1 -->Bug Fixes" },
  { message = "^doc", group = "<!-- 3 -->Documentation" },
  { message = "^perf", group = "<!-- 4 -->Performance" },
  { message = "^refactor", group = "<!-- 2 -->Refactor" },
  { message = "^style", group = "<!-- 5 -->Styling" },
  { message = "^test", group = "<!-- 6 -->Testing" },
  { message = "^chore\\(release\\): prepare for", skip = true },
  { message = "^chore\\(deps.*\\)", skip = true },
  { message = "^chore\\(pr\\)", skip = true },
  { message = "^chore\\(pull\\)", skip = true },
  { message = "^chore|^ci", group = "<!-- 7 -->Miscellaneous Tasks" },
  { body = ".*security", group = "<!-- 8 -->Security" },
  { message = "^revert", group = "<!-- 9 -->Revert" },
]
# protect breaking changes from being skipped due to matching a skipping commit_parser
protect_breaking_commits = false
# filter out the commits that are not matched by commit parsers
filter_commits = false
# regex for matching git tags
# tag_pattern = "v[0-9].*"
# regex for skipping tags
# skip_tags = ""
# regex for ignoring tags
# ignore_tags = ""
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"
# limit the number of commits included in the changelog.
# limit_commits = 42

[orhun]

Hello!

Interesting setup you have there!

Unfortunately, no links to the corresponding files are displayed in GitLab.

Can you elaborate what you want to see in the changelog instead?

A CHANGELOG.md is not created in the root directory of the repository.

I'm not very familiar with GitLab pages but don't you have to commit the file after generating it to add it to the repository?

[alerque]

No with GitLab pages you can use CI to generate stuff from your repo but you don't commit it to publish, you just put it in a special directory, typically public , and it gets picked up from there. It is quite a but more versatile that GitHub Pages in that regard.

[orhun]

Got it, thanks for the explanation!

[joergklein]

Please take a look at the screenshot. This is made from https://github.com/gohugoio/hugo/releases. It would be great when you implement the issues and the username.

---

[orhun]

Okay I see, to do that you need to update your cliff.toml to accommodate for your GitLab project.

• This template might be a good start: https://github.com/orhun/git-cliff/blob/main/examples/github.toml
• You should update your remote like this: https://git-cliff.org/docs/configuration/remote
• Then start using GitLab related variables in the template: https://git-cliff.org/docs/integration/gitlab

I'm happy to help with it. Do you want to have the same format as above?

[orhun]

I see that you are using the Alpine package. Can you verify that you're using the latest version of git-cliff? GitLab integration was added in 2.3.0.

[joergklein]

The Alpine Linux images for Hugo and git-cliff are up to date. Here is the corresponding link:

https://docker.hugomods.com/docs/tags