Forem: Alfredo orozco

🚀 Automate Your CHANGELOG with Git Cliff and Keep a Changelog

Alfredo orozco — Mon, 23 Jun 2025 02:54:33 +0000

Maintaining a CHANGELOG in our software projects is indispensable and adds professionalism and seriousness to the product.

Often we forget to update our project’s CHANGELOG—either because we consider it a waste of time, because we don’t really know every change involved, or simply because we forget.

A readable, well-organized changelog makes it easy to communicate changes to other developers, users, and team members we collaborate with. Additionally, it speeds up version auditing, reduces deployment errors, improves traceability in high-demand production environments, and builds trust with our code’s consumers.

🎯 Goal

In this post I’ll show how to use the git-cliff tool to automatically generate and maintain a CHANGELOG.md file following the Keep a Changelog standard. We’ll base everything on a commit history formatted with Conventional Commits, which is key for the automation to classify each change correctly.

This way, we’ll end up with a clear, consistent, and always-up-to-date changelog. ✅

💻 Installation & Configuration

🔧 Prerequisites

Git installed (≥ 2.20)
A commit history formatted with Conventional Commits

📲 Installation

macOS (Homebrew)

brew install git-cliff

Linux (Linuxbrew or binary)

brew install git-cliff     # if you use Linuxbrew

# or:

curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
  | tar xz -C ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Windows (Scoop or binary)

# With Scoop
scoop install git-cliff

# Or download from Releases, unzip and add to %PATH%.

⚙️ Basic Configuration

Create a cliff.toml file at the root of your project:

[git]
tag_prefix = "v"         # Prefix for semantic tags

[output]
file   = "CHANGELOG.md"
format = "MD"            # Markdown

[sections]
"🚀 Added"      = ["feat"]
"🐛 Fixed"      = ["fix"]
"🧰 Changed"    = ["perf"]
"⚠️ Deprecated" = ["chore(deprecate)"]
"🚫 Removed"    = ["feat!", "BREAKING CHANGE"]
"🔒 Security"   = ["fix(security)", "security"]

With this configuration, git-cliff will know how to read your commits and where to group them according to the Keep a Changelog conventions.

🛠️ Advanced Configuration

For mature or more complex projects, you may want to align additional commit types or scopes to well-defined sections. git-cliff lets you configure versatile grouping based on commit types and scopes:

[sections]
"🚀 Features"     = ["feat"]
"🐛 Bug Fixes"    = ["fix"]
"🧰 Improvements" = ["improvement", "perf"]
"💄 Style"        = ["style"]
"📝 Docs"         = ["docs"]
"⚠️ Deprecated"   = ["chore(deprecate)", "feat(deprecate)"]
"🚫 Removed"      = ["feat!", "BREAKING CHANGE"]
"🔒 Security"     = ["fix(security)", "security"]

improvement: small refinements instead of new features
style: formatting or linting changes
docs: anything related to documentation

If you need to add more sections, simply extend the [sections] table with the keys and list of types or scopes your team uses.

🏷️ Generating the CHANGELOG by Version

Create a tag for the new version in your repository:

   git tag v1.3.0
   git push origin --tags

Generate the changelog from the last two version tags:

   git cliff v1.2.0..v1.3.0

Or, if you don’t specify tags, it will use the automatic range since the last tag:

   git cliff

Review and commit the updated changelog:

   git add CHANGELOG.md
   git commit -m "chore: release v1.3.0"
   git push origin main

🤖 CI/CD Automation

Automating tedious tasks in your workflow saves a ton of time you can spend on higher-value activities. Automatically generating your changelog is no exception.

⚙️ GitHub Actions

name: 📦 Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'New version (e.g. 1.3.0)'
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install git-cliff
        run: |
          curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
            | tar xz -C ~/.local/bin
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Generate CHANGELOG and tag
        env:
          VERSION: ${{ github.event.inputs.version }}
        run: |
          git config user.name "CI Bot 🤖"
          git config user.email "ci@yourcompany.com"
          git tag v${VERSION}
          git cliff
          git add CHANGELOG.md
          git commit -m "chore: release v${VERSION}"
          git push origin main --tags

🐙 GitLab CI/CD

stages:
  - release

release:
  stage: release
  image: alpine:latest
  before_script:
    - apk add --no-cache curl git
    - curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
        | tar xz -C /usr/local/bin
  script:
    - git tag v$CI_COMMIT_REF_NAME
    - git cliff
    - git add CHANGELOG.md
    - git commit -m "chore: release v$CI_COMMIT_REF_NAME"
    - git push origin HEAD:main --tags
  only:
    - tags

Conclusions

As a software engineer, I’ve seen projects with neglected change traceability: undocumented versions, teams lost among branches, and unplanned deployments—both in the companies I’ve worked for and in my own side projects.

While automatic changelog generation is a powerful, versatile tool, its effectiveness depends on the team adopting and respecting commit standards—hence the importance of Conventional Commits.

With git-cliff and Keep a Changelog, you gain:

Reliable automation: your changelog reflects exactly the commits in your repo
Standardization: all changes classified and formatted consistently
Professionalism: each release ships with a clear, audited document

Integrate this flow into your project and CI/CD, and you’ll discover that maintaining an impeccable change history is not only simple, but adds immense value to your software’s quality and trustworthiness.

Until next time!

🚀 Generación automática de CHANGELOG con git-cliff y Convetional Commits

Alfredo orozco — Mon, 23 Jun 2025 02:40:48 +0000

Mantener un CHANGELOG en nuestros proyectos de software es indispensable y agrega profesionalismo y seriedad al producto.
Muchas veces olvidamos actualizar el CHANGELOG de nuestros proyectos ya sea por que consideramos que es una pérdida de tiempo, porque no sabes en realidad de todos los cambios implicados o simplemente porque lo olvidamos.

Un changelog legible y ordenado facilita comunicar los cambios a otros desarrolladores, usuarios y miembros del equipo con el que trabajamos. Además, acelera la auditoría de versiones, reduce errores en despliegues y mejora la trazabilidad en entornos de producción de alta demanda y genera confianza entre los usuarios de nuestro código.

🎯 Objetivo

En este post mostraré cómo usar la herramienta git-cliff para generar y mantener automáticamente un archivo CHANGELOG.md siguiendo el estándar Keep a Changelog. Todo ello se basará en un historial de commits formateados con Conventional Commits, lo cual es clave para que la automatización clasifique cada cambio correctamente.

De esta forma obtendremos un archivo claro, uniforme y siempre actualizado. ✅

💻 Instalación y configuración

🔧 Requisitos previos

Git instalado (≥ 2.20).
Historial de commits limpio con Conventional Commits.

📲 Instalación

macOS (Homebrew)

brew install git-cliff

Linux (Linuxbrew o binario)

brew install git-cliff     # si usas Linuxbrew

# o bien:

curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
  | tar xz -C ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Windows (Scoop o binario)

# Con Scoop
scoop install git-cliff

# O descarga desde Releases, descomprime y agrega a %PATH%.

⚙️ Configuración básica

Crea cliff.toml en la raíz de tu proyecto:

[git]
tag_prefix = "v"         # Prefijo de las etiquetas semánticas

[output]
file   = "CHANGELOG.md"
format = "MD"            # Markdown

[sections]
"🚀 Added"      = ["feat"]
"🐛 Fixed"      = ["fix"]
"🧰 Changed"    = ["perf"]
"⚠️ Deprecated" = ["chore(deprecate)"]
"🚫 Removed"    = ["feat!", "BREAKING CHANGE"]
"🔒 Security"   = ["fix(security)", "security"]

Con esto, git-cliff sabrá de cómo leer los commits y dónde agruparlos según las convenciones de Keep a Changelog.

🛠️ Configuración avanzada

Para proyectos maduros o más complejos, tal vez necesites alinear más tipos de commits con secciones claras o con un formato definido por tu equipo de trabajo. git-cliff permite una configuración versátil para agrupar los cambios en las secciones en base a los tipos y scopes de los commits.

[sections]
"🚀 Features"     = ["feat"]
"🐛 Bug Fixes"    = ["fix"]
"🧰 Improvements" = ["improvement", "perf"]
"💄 Style"        = ["style"]
"📝 Docs"         = ["docs"]
"⚠️ Deprecated"   = ["chore(deprecate)", "feat(deprecate)"]
"🚫 Removed"      = ["feat!", "BREAKING CHANGE"]
"🔒 Security"     = ["fix(security)", "security"]

improvement: pequeños refinamientos en lugar de nuevas features.
style: cambios de formato o linting.
docs: todo lo relativo a documentación.

Si necesitas añadir más secciones, simplemente amplía el [sections] con la clave y la lista de tipos o scopes que uses en tu equipo.

🏷️ Generar el CHANGELOG por versión

Primero debes crear un tag para la versión en tu repositorio:

git tag v1.3.0
git push origin --tags

Después, genera el changelog desde los 2 últimos tags de versionado:

git cliff v1.2.0..v1.3.0

o, si no especificas los tags, se usará el rango automático desde la última etiqueta.

git cliff

Revisa que el archivo se haya actualizado correctamente y haz el commit:

git add CHANGELOG.md
git commit -m "chore: release v1.3.0"
git push origin main

🤖 Automatización en CI/CD

Automatizar tareas tediosas lo más que se pueda en un flujo de trabajo, nos ahorra un montón de tiempo que podemos aprovechar para realizar otras tareas y mejorar nuestra productividad. La generación de CHANGELOG automáticamente no es la excepción.

⚙️ GitHub Actions

name: 📦 Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Nueva versión (ej. 1.3.0)'
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Instalar git-cliff
        run: |
          curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
            | tar xz -C ~/.local/bin
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Generar CHANGELOG y tag
        env:
          VERSION: ${{ github.event.inputs.version }}
        run: |
          git config user.name "CI Bot 🤖"
          git config user.email "ci@yourcompany.com"
          git tag v${VERSION}
          git cliff
          git add CHANGELOG.md
          git commit -m "chore: release v${VERSION}"
          git push origin main --tags

🐙 GitLab CI/CD

stages:
  - release

release:
  stage: release
  image: alpine:latest
  before_script:
    - apk add --no-cache curl git
    - curl -sSL https://github.com/jackfirth/git-cliff/releases/download/v0.5.1/git-cliff_0.5.1_Linux_x86_64.tar.gz \
        | tar xz -C /usr/local/bin
  script:
    - git tag v$CI_COMMIT_REF_NAME
    - git cliff
    - git add CHANGELOG.md
    - git commit -m "chore: release v$CI_COMMIT_REF_NAME"
    - git push origin HEAD:main --tags
  only:
    - tags

Conclusiones

Como ingeniero de software he visto proyectos descuidados en cuanto a trazabilidad de cambios: versiones sin documentación, equipos perdidos entre branches y despliegues imprevistos, y no solo en los distintos lugares en los que eh trabajado sino también en proyectos propios.

Aunque la generación automática de changelogs es una herramienta muy versátil y de mucha ayuda, es necesario que el equipo adopte una cultura donde se respeten los estándares y convenciones para realizar los commits, ya que esta herramienta depende totalmente de ello utilizando Conventional Commits.

Con git-cliff y Keep a Changelog, obtenemos:

Automatización fiable: tu changelog refleja exactamente los commits de tu repo.
Estandarización: todos los cambios clasificados y formateados de la misma manera.
Profesionalismo: cada release va acompañado de un documento legible y auditado.

Integra este flujo en tu proyecto y CI/CD, y descubrirás que mantener un historial de cambios impecable no solo es sencillo, sino que aporta un valor incalculable a la calidad y confianza de tu software.

¡Hasta la próxima!