Install via Docker

Run git-cliff in Docker containers without local installation.

Quick Start

Docker Hub
GitHub Container Registry

Run git-cliff from Docker Hub:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest

Run from GitHub Container Registry:

docker run -t -v "$(pwd):/app/" ghcr.io/orhun/git-cliff/git-cliff:latest

Available Images

Docker images are available in two registries:

Registry	Image URL	Updates
Docker Hub	`orhunp/git-cliff`	Automated on release
GitHub CR	`ghcr.io/orhun/git-cliff/git-cliff`	Automated on release

Available Tags

Images follow these tagging conventions:

Tag	Description	Example
`latest`	Latest stable release	`orhunp/git-cliff:latest`
`X.Y.Z`	Specific version (SemVer)	`orhunp/git-cliff:2.7.0`
`main`	Latest from main branch	`orhunp/git-cliff:main`
`sha-<short>`	Specific commit SHA	`orhunp/git-cliff:sha-954106f`

Usage Examples

Basic usage

Run in your git repository:

cd /path/to/your/git/repo
docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest

This mounts your current directory to /app/ in the container.

Generate changelog

Output to a file:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest -o CHANGELOG.md

Use custom config

With a custom configuration file:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest --config cliff.toml

Specific version

Use a specific version:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:2.7.0

Advanced Usage

Shell Alias
Docker Compose
CI/CD Pipeline
Makefile Integration

Create a convenient shell alias:Bash/Zsh:

# Add to ~/.bashrc or ~/.zshrc
alias git-cliff='docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest'

Then reload:

source ~/.bashrc

Usage:

git-cliff -o CHANGELOG.md

Use with Docker Compose:

docker-compose.yml

version: '3.8'

services:
  git-cliff:
    image: orhunp/git-cliff:latest
    volumes:
      - .:/app
    command: -o CHANGELOG.md

Run:

docker-compose run git-cliff

GitHub Actions example:

.github/workflows/changelog.yml

name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    container:
      image: orhunp/git-cliff:latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Generate changelog
        run: git-cliff -o CHANGELOG.md
      
      - name: Upload changelog
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: CHANGELOG.md

GitLab CI example:

.gitlab-ci.yml

changelog:
  image: orhunp/git-cliff:latest
  script:
    - git-cliff -o CHANGELOG.md
  artifacts:
    paths:
      - CHANGELOG.md
  only:
    - tags

Add to your Makefile:

Makefile

DOCKER_IMAGE := orhunp/git-cliff:latest

.PHONY: changelog
changelog:
	docker run -t -v "$(PWD):/app/" $(DOCKER_IMAGE) -o CHANGELOG.md

.PHONY: changelog-latest
changelog-latest:
	docker run -t -v "$(PWD):/app/" $(DOCKER_IMAGE) --latest

.PHONY: changelog-unreleased
changelog-unreleased:
	docker run -t -v "$(PWD):/app/" $(DOCKER_IMAGE) --unreleased

Usage:

make changelog

Building Custom Images

Build your own Docker image:

Clone the repository

git clone https://github.com/orhun/git-cliff.git
cd git-cliff

Build the image

DOCKER_BUILDKIT=1 docker build -t git-cliff .

Using BuildKit enables better caching and faster builds.

Run your custom image

docker run -t -v "$(pwd):/app/" git-cliff

Volume Mounting

Understanding volume mounts:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest

Common Commands

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest -o CHANGELOG.md

Troubleshooting

Permission denied when writing files

The container runs as a specific user. Fix ownership:

# Run with your user ID
docker run -t -v "$(pwd):/app/" --user $(id -u):$(id -g) orhunp/git-cliff:latest

Or fix permissions after:

sudo chown -R $USER:$USER .

Git directory not found

Ensure you’re mounting the git repository root:

# Check you're in a git repo
git rev-parse --show-toplevel

# Run from repo root
cd $(git rev-parse --show-toplevel)
docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest

Config file not found

Make sure the config file is in the mounted directory:

# List files to verify
ls -la cliff.toml

# Run with explicit path
docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest --config /app/cliff.toml

Image pull fails

If pulling from Docker Hub fails, try GitHub Container Registry:

docker pull ghcr.io/orhun/git-cliff/git-cliff:latest
docker run -t -v "$(pwd):/app/" ghcr.io/orhun/git-cliff/git-cliff:latest

Or authenticate with GitHub:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Windows path issues

On Windows, use PowerShell:

docker run -t -v "${PWD}:/app/" orhunp/git-cliff:latest

Or use WSL2:

docker run -t -v "$(pwd):/app/" orhunp/git-cliff:latest

Get Started

Installation

Usage

Configuration

Templating

Install via Docker

Install via Docker

Quick Start

Available Images

Available Tags

Usage Examples

Advanced Usage

Building Custom Images

Volume Mounting

Common Commands

Troubleshooting

Next Steps

Configuration

CI/CD Integration

Build docs developers (and LLMs) love

Get Started

Installation

Usage

Configuration

Templating

​Install via Docker

​Quick Start

​Available Images

​Available Tags

​Usage Examples

​Advanced Usage

​Building Custom Images

​Volume Mounting

​Common Commands

​Troubleshooting

​Next Steps

Configuration

CI/CD Integration

Build docs developers (and LLMs) love

Install via Docker

Quick Start

Available Images

Available Tags

Usage Examples

Advanced Usage

Building Custom Images

Volume Mounting

Common Commands

Troubleshooting

Next Steps