---
url: https://relizy.dev/commitlint.md
description: >-
  Lint commit messages with your Relizy config, in a commit-msg hook (husky,
  simple-git-hooks, lefthook) and in CI (GitHub Actions, GitLab CI). Same
  parser, types and scopes as your releases, commit bodies checked as they will
  appear in your changelogs.
---

# Commit linting

`relizy commitlint` checks commit messages **with your Relizy config**: the parser, the types and the packages of your releases. A commit that passes is the commit Relizy will bump, list and render in your changelogs.

## Why not commitlint?

* **One source of truth**: the types come from [`types`](./../config/changelog.md#types), the scopes from your workspace packages and `scopeMap`. No second config to keep in sync.
* **The release parser**: commitlint uses `conventional-commits-parser`, Relizy its own. A message accepted by commitlint can be ignored or classified differently by your release.
* **Bodies checked**: Relizy copies commit bodies into your changelogs and release notes. Each body is rendered as in the changelog, and its code blocks are checked with your ESLint or a built-in parser.
* **No extra dependency**: it ships with Relizy (`pnpm add -D relizy`), no `@commitlint/*` package needed.

## What it checks

| Area             | Checks                                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Header           | `type(scope)!: subject` format, known type, header length, subject period and meaning (and case, opt-in)                                      |
| Scopes           | Workspace packages, `scopeMap` keys and your list, required scope (opt-in), scope matching the changed files, one released package per commit |
| Body             | Blank line after the header, no markdown heading, valid markdown, changelog entry that keeps the changelog valid                              |
| Breaking changes | Only `!` or a `BREAKING CHANGE:` footer can trigger a major bump                                                                              |
| AI attribution   | No AI co-author, session trailer or "Generated with" line                                                                                     |

Every rule can be tuned or disabled, and you can write your own: see [Rules](./rules.md) and [Custom Rules](./custom-rules.md). No config is required to start; see [Configuration](./config.md) to tune it.

## Lint the commit being created

```bash
npx relizy commitlint --install
```

It writes a `commit-msg` hook running `relizy commitlint --edit "$1"`: in `.husky/` when [husky](https://typicode.github.io/husky) is set up, otherwise in the hooks directory of git (`core.hooksPath` or `.git/hooks`). An existing hook is kept (with a warning) unless you add `--force`. [`relizy init`](./../cli/init.md) offers to install it too.

`.git/hooks` is not versioned: the hook only exists on the clone that wrote it, and the commits go through while relizy is not installed. To set it up on every clone, run the command at each install (`relizy init` adds it when it writes the hook there):

```json
{
  "scripts": {
    "prepare": "relizy commitlint --install"
  }
}
```

Outside a git repository (a Docker build), it installs nothing and does not fail. With husky, the hook is in `.husky/`, versioned with the project, and the one relizy wrote in `.git/hooks` before husky is removed.

To write it by hand:

::: code-group

```bash [husky]
# .husky/commit-msg
npx --no -- relizy commitlint --edit "$1"
```

```json [simple-git-hooks]
{
  "simple-git-hooks": {
    "commit-msg": "npx --no -- relizy commitlint --edit \"$1\""
  }
}
```

```yaml [lefthook]
# lefthook.yml
commit-msg:
  commands:
    relizy-commitlint:
      run: npx --no -- relizy commitlint --edit {1}
```

:::

With simple-git-hooks, run `npx simple-git-hooks` to apply the config to git.

## Lint the commits of a pull request

A commit can skip the hook (`--no-verify`, the web interface of GitHub or GitLab). Lint the commits in CI too: without `--from`, Relizy lints the commits of the pull or merge request (see [default range](./cli.md#default-range)) and fetches the missing history of a shallow clone.

::: code-group

```yaml [GitHub Actions]
# .github/workflows/commitlint.yml
name: Commit messages

on:
  pull_request:
    # `edited`: lint the title again when it changes (commitlint.title)
    types: [opened, synchronize, reopened, edited]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: relizy/action@v2
        with:
          command: commitlint
```

```yaml [GitLab CI]
# .gitlab-ci.yml
include:
  - component: gitlab.com/relizy/relizy/commitlint@2
```

:::

The [relizy action](./../guide/github-actions.md#lint-the-commits-of-pull-requests) and the [`commitlint` component](./../guide/gitlab-ci.md#lint-the-commits-of-merge-requests) set up your package manager and your dependencies, and pass their `args` to the command (`args: --title --quiet`). Without them, install your dependencies and run `npx relizy commitlint` in the job.

The title of the pull or merge request is linted too, as its merge uses it: a **squash merge** turns it into the commit Relizy reads for the bump and the changelog, and drops the commits. By default ([`commitlint.title: 'auto'`](./config.md#title)), Relizy reads the merge method from your provider: the title fails the check when the merge squashes for sure and only warns when the merge method is chosen at the merge, and the commits only warn when the squash drops them. In GitHub Actions, each problem is also reported as an annotation on the pull request.

## Read the output

A valid commit prints one line with its effect on the next release:

```text
✔ feat(nuxt) → minor bump, 🚀 Enhancements
```

An invalid commit prints each problem with its rule and how to fix it, a suggested header when the mistakes can be fixed safely, the documentation of the failing rules and how to commit again. The hook stops the commit:

```text
✖ fix(nuxtt): Typo.

  ✖ scope-enum          The scope "nuxtt" is not allowed
                        → did you mean "nuxt"? use a workspace package or one of: core,
                          @maz-ui/core, nuxt, @maz-ui/nuxt
  ✖ subject-full-stop   The subject ends with a period
                        → remove the final period
  ✖ subject-meaningful  The subject "Typo." does not describe the change
                        → describe what changed, in at least 2 words or 15 characters

  Suggested header: fix(nuxt): Typo
                    still to fix: subject-meaningful

────────────────────────────────────────────────────────────────────────
✖ The commit message is invalid: 3 errors, 0 warnings
  Rules: scope-enum          https://relizy.dev/commitlint/rules#scope-enum
         subject-full-stop   https://relizy.dev/commitlint/rules#subject-full-stop
         subject-meaningful  https://relizy.dev/commitlint/rules#subject-meaningful
  Fix:   edit the message and commit again, it is kept in .git/COMMIT_EDITMSG:
           $ git commit --edit --file .git/COMMIT_EDITMSG
```

Warnings are printed but never fail. `--preview` adds the changelog entry of each commit, `--format json` prints the report for programs: see [CLI](./cli.md). AI agents can lint a message before committing with the `lint_commit` tool of the [MCP server](./../guide/ai-agents.md).

## Next steps

* [Rules](./rules.md): what is checked and how to tune it.
* [Custom Rules](./custom-rules.md): your own rules as functions.
* [Configuration](./config.md): the `commitlint` key of `relizy.config.ts`.
* [Migrating from commitlint](./migration.md): replace your commitlint config.
