zaventh/commitlint repository overview

⁠docker-commitlint

docker-commitlint bundles commitlint⁠ with an opinionated configuration into a small, ready-to-run container. There is nothing to install beyond Docker — no Node.js, no npm, no local commitlint setup. Pull the image and pipe a commit message to it.

⁠Table of contents

• What it checks⁠
• Quick start⁠
• Usage⁠
  • As a standalone CLI⁠
  • As a pre-commit hook⁠
  • As a GitHub Action⁠
• Configuration⁠
• FAQ⁠
• License⁠
• Attributions⁠

⁠What it checks

The image ships with a commitlint.config.js⁠ that applies two rule sets:

Valid — passes:

feat: add support for relaxed linting
fix(parser): handle empty commit body
docs: update usage examples

Blocked — unknown type fails with exit code 1:

wibble: this is not a conventional type

Warned — wrong tense is flagged but still allowed through:

feat: added a new feature
⚠  tense of subject must be present-imperative. Words in other tenses: added - past-tense [tense/subject-tense]

⁠Quick start

docker pull zaventh/commitlint
echo "feat: add a new feature" | docker run --rm -i zaventh/commitlint

An empty (exit code 0) result means the message is valid.

⁠Usage

The image can be used in three ways.

⁠1. As a standalone CLI

Lint a single message by piping it to the container over stdin:

echo "feat: add a new feature" | docker run --rm -i zaventh/commitlint

Lint a range of existing commits by mounting your repository's .git directory into the container:

docker run --rm \
  -v "$(git rev-parse --show-toplevel)/.git:/app/.git" \
  -i zaventh/commitlint --from HEAD~1

Any arguments after the image name are passed straight through to commitlint⁠ (e.g. --from, --to, --edit).

⁠2. As a pre-commit hook

The image can back a pre-commit⁠ hook. A ready-made commitlint pre-commit hook⁠ can be wired into your .pre-commit-config.yaml:

- repo: https://github.com/extenda/pre-commit-hooks
  rev: v0.4
  hooks:
    - id: commitlint
      stages: [commit-msg]

⁠3. As a GitHub Action

For GitHub Actions, the image exposes an alternative entrypoint at /app/bin/action.sh:

Usage: action.sh [-c <sha>] [-x <bool>] [-m <string>]

Example step:

- name: Lint commit messages
  run: |
    docker run --rm \
      -v "${{ github.workspace }}/.git:/app/.git" \
      --entrypoint /app/bin/action.sh \
      zaventh/commitlint -c "${{ github.event.pull_request.base.sha }}" -x true

⁠Configuration

The full configuration lives in commitlint.config.js⁠:

module.exports = {
  extends: [
    '@commitlint/config-conventional',
  ],
  plugins: [
    'commitlint-plugin-tense',
  ],
  rules: {
    'tense/subject-tense': [1, 'always'],
  }
};

To change the rules, fork this repository, edit commitlint.config.js, and rebuild the image:

docker build -t my-commitlint .

⁠FAQ

What is this? A Docker image that validates Git commit messages against the Conventional Commits spec, with an added imperative-mood check on the subject line.

Do I need Node.js or npm installed? No. Everything runs inside the container. You only need Docker.

Does a wrong verb tense fail my commit? No. The imperative-mood rule (tense/subject-tense) is configured as a warning, so it is advisory. Only violations of the Conventional Commits structure cause a non-zero exit code.

How do I lint a range of commits instead of a single message? Mount your repo's .git directory into the container and pass --from/--to, e.g. --from HEAD~1. See As a standalone CLI⁠.

What base image and versions does it use? node:24-alpine with @commitlint/cli and @commitlint/config-conventional at v21, plus commitlint-plugin-tense.

Where is the Docker image published? On Docker Hub as zaventh/commitlint⁠.

⁠License

This project is licensed under the MIT license⁠.

⁠Attributions

• Forked from Extenda Retail's docker-commitlint⁠, then modernized and customized.
• The imperative-mood word list is derived from the MIT-licensed git-good-commit⁠ project.