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

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 "[email protected]"
          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!