diff --git a/profile/README.md b/profile/README.md index 4231f3f..b253ac5 100644 --- a/profile/README.md +++ b/profile/README.md @@ -7,34 +7,76 @@ Commit Check — Clean commits. Clear standards. -Enforce commit message, branch naming, author, and signoff standards — -one policy, across your CLI, pre-commit, CI, and AI agents. +An open policy engine for Git commit metadata — one versioned file, enforced everywhere. [![PyPI](https://img.shields.io/pypi/v/commit-check?logo=pypi&logoColor=white&color=2c9ccd)](https://pypi.org/project/commit-check/) [![Downloads](https://img.shields.io/pypi/dm/commit-check?color=2c9ccd)](https://pypi.org/project/commit-check/) [![Marketplace](https://img.shields.io/badge/Marketplace-commit--check--action-2c9ccd?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/commit-check-action) [![License: MIT](https://img.shields.io/badge/License-MIT-2c9ccd.svg)](https://opensource.org/licenses/MIT) [![Website](https://img.shields.io/badge/Website-commit--check.com-2c9ccd?logo=git&logoColor=white)](https://commit-check.com) - + --- -## Why Commit Check - -**Commit Check** (aka **cchk**) is an open-source policy engine for Git commit -metadata — commit messages, branch names, committer name/email, signoff, and -more — helping teams keep a **consistent, compliant, and clean Git history**. - -Define your rules once in a single versioned config, and enforce them -identically everywhere: on a developer's machine, in CI, and in AI-assisted -workflows. - -It's a lightweight, open alternative to GitHub Enterprise -[metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) -and Bitbucket's paid -[Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), -built for a modern DevOps and Infrastructure-as-Code workflow. +## What it looks like + +```text +CC001 message check failed ==> updated the parser +The commit message should follow Conventional Commits. See https://www.conventionalcommits.org +Suggest: Use (): , where is one of: feat, fix, docs, ... +Docs: https://commit-check.com/rules/#cc001 +``` + +Every failure names a **stable rule ID**, the value that failed, what to do +about it, and where it is documented — as text, JSON, a job summary, a PR +comment, or an MCP tool call. + +## One policy, four places + +``` + cchk.toml + │ + ┌─────────────────┼─────────────────┬─────────────────┐ + ▼ ▼ ▼ ▼ + your machine pre-commit GitHub CI AI agents + (commit-check) hook Action (MCP) + │ │ │ │ + └─────────────────┴────────┬────────┴─────────────────┘ + ▼ + same rules, same verdict +``` + +Write the rules once. Every surface reads that same file, so a commit that +passes on a laptop passes in CI — and an agent asking *"would this message be +accepted?"* gets the answer your maintainers actually configured. + +## Quick start + +Nothing to configure to begin with: the defaults enforce Conventional Commits, +Conventional Branch, and sane subject lengths. + +```yaml +# .pre-commit-config.yaml — feedback while the message is still being written +repos: + - repo: https://github.com/commit-check/commit-check + rev: v2.13.4 + hooks: + - id: check-message + - id: check-branch +``` + +```yaml +# .github/workflows/commit-check.yml — where it becomes a policy, not a suggestion +- uses: commit-check/commit-check-action@v2 + with: + message: true + branch: true + pr-title: true + pr-comments: true # needs permissions: pull-requests: write +``` + +Every rule and option is at **[commit-check.com](https://commit-check.com)**. ## The Commit Check family @@ -45,26 +87,34 @@ built for a modern DevOps and Infrastructure-as-Code workflow. | [**commit-check-mcp**](https://github.com/commit-check/commit-check-mcp) | Model Context Protocol server | Letting AI agents validate against your rules | -## Key features +## What it does not do -- ✅ **Conventional Commits** & **Conventional Branch** enforcement -- ✅ **Author** name / email validation with configurable patterns -- ✅ **Signoff (DCO)** verification -- ✅ **Rebase / merge-base** and **force-push** safety checks -- ✅ **AI attribution governance** — detect or forbid AI-generated commit trailers -- ✅ **One config** (`cchk.toml`), with org-level inheritance, shared across CLI, pre-commit & CI -- ✅ **Job summaries & PR comments**, plus **JSON output** and **MCP tools** for automation and AI agents +- It reads commit **metadata**, not your code. It is not a linter. +- A pre-commit hook can be skipped with `--no-verify`, so only the CI check is + really a policy — the hook is there to save you the round trip. +- Imperative-mood checking reads a word's *form*, so a subject led by a noun + that looks like a gerund (`fix: spelling in the docs`) gets reported. -## Trusted & secure +## Where Commit Check fits -- 🔒 **SLSA Level 3** build provenance, with artifact attestation verified at install time -- 🏢 Used by teams at **Apache**, **Texas Instruments**, **Mila**, and [many more](https://github.com/commit-check/commit-check-action/network/dependents) -- 📖 **MIT licensed**, actively maintained, and following [Conventional Commits](https://www.conventionalcommits.org/) and [Conventional Branch](https://conventional-branch.github.io/) +Commit metadata rules are usually behind a paid tier: GitHub's +[metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) +need Enterprise, and Bitbucket's equivalent is +[Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), +a paid Marketplace app. Commit Check is the open alternative — and because the +policy is a file in your repository rather than a settings page, it can be +reviewed, diffed, and rolled back like anything else you version. + +- 🔒 **SLSA Level 3 build provenance** — verify any release yourself with + `gh attestation verify --repo commit-check/commit-check` +- 🏢 Runs in repositories across **Apache**, **Texas Instruments**, **Mila**, and + [many more](https://github.com/commit-check/commit-check-action/network/dependents) +- 📖 MIT licensed, actively maintained, and itself following + [Conventional Commits](https://www.conventionalcommits.org/) and + [Conventional Branch](https://conventional-branch.github.io/) ## Get involved -We welcome feedback, bug reports, and feature requests from the community. - -- [Issues](https://github.com/commit-check/commit-check/issues) — bug reports & feature requests -- [Discussions](https://github.com/commit-check/commit-check/discussions) — questions, ideas, and community conversations -- [Documentation](https://commit-check.com) — guides, configuration reference, and more +[Issues](https://github.com/commit-check/commit-check/issues) for bugs and feature +requests · [Discussions](https://github.com/commit-check/commit-check/discussions) +for questions and ideas · [Docs](https://commit-check.com) for everything else.