Catch bad commits before they merge.

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

Commit Check is commit policy as code for teams and AI agents. It 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.

On GitHub? Install the Commit Check App and every push and pull request gets a check run, with no workflow file. It is free for public repositories and personal accounts.

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.19.4
    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",
  "reason": ""
}

A check that did not run has status skip, and reason says why when the author is on an ignore_authors list: "author dependabot[bot] is in [commit].ignore_authors".

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, holds a regex that does not compile or gives a [commit] or [branch] setting a value of the wrong type (subject_max_length = "abc"). A [files] value it cannot use turns that rule off with a notice instead. --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.