diff --git a/README.md b/README.md index 0c37d438..c9cb5561 100644 --- a/README.md +++ b/README.md @@ -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) - -
+ + + Commit Check PR comment: a commit failing CC001 and CC003 and an author email failing CC102, each linked to its rule documentation + ## 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 diff --git a/assets/pr-comment-dark.png b/assets/pr-comment-dark.png new file mode 100644 index 00000000..0f80ce90 Binary files /dev/null and b/assets/pr-comment-dark.png differ diff --git a/assets/pr-comment-light.png b/assets/pr-comment-light.png new file mode 100644 index 00000000..a4a13e3d Binary files /dev/null and b/assets/pr-comment-light.png differ