Catch bad commits before they merge.

Docs · Rules · GitHub Action · GitHub App · MCP server

Commit Check validates commit messages, branch names, authors, sign-offs, tags, committed files and AI attribution against one cchk.toml — in your commit hook, in CI, on every pull request and inside your AI agent. When the fix is obvious, it hands you the line.

pip install commit-check        # Python 3.10+
commit-check --message --branch

No config needed: out of the box it checks Conventional Commits and Conventional Branch.

Stop bad commits before they exist. In .pre-commit-config.yaml:

repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.18.1
    hooks:
      - id: check-message
      - id: check-branch

Add args: [--fix] to check-message and the hook corrects mechanical slips itself — a type's case, a missing colon — instead of rejecting the commit. The hooks for the other checks (check-author-name, check-author-email, check-no-force-push, check-tag, check-files) are listed in the pre-commit guide.

The same cchk.toml drives all of them:

Every rule, with examples: commit-check.com/rules

Put a cchk.toml (or commit-check.toml) in the repository root or in .github/:

[commit]
subject_max_length = 72
require_signed_off_by = true
ai_attribution = "disclose"
ignore_authors = ["dependabot[bot]", "renovate[bot]"]

[branch]
conventional_branch = true

• Roll out gently: warn = ["CC003"] reports a rule in full without failing the run.
• One policy per organization: inherit_from = "github:my-org/.github:cchk.toml" — see organization config.
• Override anywhere: every key has a CLI flag and a CCHK_* environment variable.
• Editor support: the schema is on SchemaStore, so VS Code and JetBrains autocomplete cchk.toml.

--format json gives each check a stable rule ID, the value it saw and a suggestion — plus the corrected value itself when the correction is mechanical, so an agent can apply it without interpreting anything:

echo "Fix: add streaming support" | commit-check -m --format json

The failing entry of its checks array:

{
  "rule_id": "CC001",
  "check": "message",
  "status": "fail",
  "value": "Fix: add streaming support",
  "error": "The commit message should follow Conventional Commits. See https://www.conventionalcommits.org",
  "suggest": "Use \"fix: add streaming support\"",
  "fix": "fix: add streaming support",
  "docs_url": "https://commit-check.com/rules/#cc001"
}

The same result, without a subprocess:

from commit_check.api import validate_message

validate_message("feat: add streaming support")["status"]  # "pass"

commit_check.api also has validate_branch, validate_author, validate_tag, validate_push and validate_all, all returning the same shape. Unlike the CLI they do not read cchk.toml: pass the policy as a config dict. The Python API page covers each function and how to load a repository's file.

Exit codes: 0 passed · 1 a check failed · 2 nothing was checked — bad usage, or a config that is missing, is not valid TOML, names an unknown rule or holds a regex that does not compile. --dry-run reports everything and exits 0. More output formats: examples.

*Push rulesets need a Team or Enterprise plan for private repositories. The full comparison, including YACC and custom hooks: commit-check.com/compare

[![commit-check](https://commit-check.com/badge.svg)](https://commit-check.com)

Questions and ideas go to Discussions, bugs to Issues. Releases follow Semantic Versioning. Released under the MIT License.