commit-check · shenxianpeng · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026
@@ -9,70 +9,105 @@
 [![CodeCov](https://codecov.io/gh/commit-check/commit-check/branch/main/graph/badge.svg?token=GC2U5V5ZRT)](https://codecov.io/gh/commit-check/commit-check)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/commit-check/commit-check/badge)](https://api.securityscorecards.dev/projects/github.com/commit-check/commit-check)
 
-## Table of Contents
+**One versioned policy for Git commit metadata — enforced in the terminal, in hooks, in CI, and on your AI agents.**
 
-- [Overview](#overview)
-- [Quick Start](#quick-start)
-- [Installation](#installation)
-- [Configuration](#configuration)
-  - [Use Default Configuration](#use-default-configuration)
-  - [Use Custom Configuration File](#use-custom-configuration-file)
-  - [Organization-Level Configuration (inherit_from)](#organization-level-configuration-inherit_from)
-  - [Use CLI Arguments or Environment Variables](#use-cli-arguments-or-environment-variables)
-  - [Check Push Safety](#check-push-safety)
-- [AI-Native Usage](#ai-native-usage)
-  - [Machine-Readable JSON Output (--format json)](#machine-readable-json-output---format-json)
-  - [Quieter Human-Readable Output](#quieter-human-readable-output)
-  - [Python API (no subprocess required)](#python-api-no-subprocess-required)
-- [Examples](#examples)
-- [Badging your repository](#badging-your-repository)
-- [Why Commit Check?](#why-commit-check)
-- [Versioning](#versioning)
-- [Have question or feedback?](#have-question-or-feedback)
-- [License](#license)
-
-## Overview
-
-**Commit Check** is a lightweight policy engine for Git commit metadata.
+Commit Check validates commit messages, branch names, author identity, signoff
+trailers, AI attribution, and push safety. The rules live in one TOML file in
+your repository; the CLI, pre-commit, GitHub Actions, and AI automation all
+enforce the same ones.
 
-It validates commit messages, branch names, author identity, signoff trailers,
-AI attribution policy, and push safety — using one versioned TOML policy across
-local hooks, CI, GitHub Actions, and AI automation.
+This is what a pull request sees when something slips — the offending value,
+each failed rule linked to its documentation, everything that passed folded
+away:
 
-- **One policy file:** `cchk.toml`
-- **Multiple enforcement points:** CLI, pre-commit, CI / GitHub Actions
-- **Machine-readable output:** JSON + Python API for automation and AI agents
-
-![commit-check demo](https://github.com/commit-check/commit-check/raw/main/assets/demo.gif)
-
-<br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/commit-check/commit-check/raw/main/assets/pr-comment-dark.png">
+  <img alt="Commit Check PR comment: a commit failing CC001 and CC003 and an author email failing CC102, each linked to its rule documentation" src="https://github.com/commit-check/commit-check/raw/main/assets/pr-comment-light.png" width="720">
+</picture>
 
 ## Quick Start
 
-**1. Install and run with zero configuration:**
+**1. Run it once with zero configuration:**
 
 ```bash
 pip install commit-check
 commit-check --message --branch
 ```
 
-**2. Add to your pre-commit hooks** (`.pre-commit-config.yaml`):
+**2. Enforce it on every commit** (`.pre-commit-config.yaml`):
 
 ```yaml
 repos:
   - repo: https://github.com/commit-check/commit-check
-    rev: v2.12.2
+    rev: v2.14.0
     hooks:
       - id: check-message
       - id: check-branch
 ```
 
-**3. Add a badge to your repository:**
+**3. Enforce it on every pull request** (`.github/workflows/commit-check.yml`):
+
+```yaml
+name: Commit Check
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write  # pr-comments needs this
+
+jobs:
+  commit-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: commit-check/commit-check-action@v2
+        with:
+          message: true
+          branch: true
+          author-name: true
+          author-email: true
+          pr-title: true
+          job-summary: true
+          pr-comments: true
+```
+
+The comment in the screenshot above is what `pr-comments` posts. On pull
+requests from forks the token is read-only, so the comment is skipped —
+[the action's docs](https://github.com/commit-check/commit-check-action/blob/main/docs/fork-pr-comments.md)
+show a two-workflow setup that covers forks too. The author checks validate
+the checkout's resolved author, one scope per run.
+
+**4. Say so:**
 
 ```text
 [![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd)](https://github.com/commit-check/commit-check)
 ```
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Use Default Configuration](#use-default-configuration)
+  - [Use Custom Configuration File](#use-custom-configuration-file)
+  - [Organization-Level Configuration (inherit_from)](#organization-level-configuration-inherit_from)
+  - [Use CLI Arguments or Environment Variables](#use-cli-arguments-or-environment-variables)
+  - [Check Push Safety](#check-push-safety)
+- [AI-Native Usage](#ai-native-usage)
+  - [Machine-Readable JSON Output (--format json)](#machine-readable-json-output---format-json)
+  - [Quieter Human-Readable Output](#quieter-human-readable-output)
+  - [Python API (no subprocess required)](#python-api-no-subprocess-required)
+- [Examples](#examples)
+- [Badging your repository](#badging-your-repository)
+- [Why Commit Check?](#why-commit-check)
+- [Versioning](#versioning)
+- [Have question or feedback?](#have-question-or-feedback)
+- [License](#license)
+
 ## Installation
 
 To install Commit Check, you can use pip:
@@ -478,6 +513,10 @@ For detailed usage instructions including pre-commit hooks, CLI commands, and ST
 
 ## Examples
 
+What the CLI looks like in the terminal:
+
+![commit-check demo](https://github.com/commit-check/commit-check/raw/main/assets/demo.gif)
+
 ### Check Commit Message Failed
 
 ```text