Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ page that documents it.

| Version | What changed | Documented in |
|---|---|---|
| [2.21.0](#v2210) | A pull request description must tick one of its template's AI declaration checkboxes (opt-in) | [CC501](rules.md#cc501) · [Requiring the template's AI declaration](guides/policies.md#requiring-the-templates-ai-declaration) |
| [2.20.5](#v2205) | The author checks cover a repository's first commit; a run takes about half the time to start; releases on PyPI carry provenance | [Checking the committer](example.md#checking-the-committer) · [CC017](rules.md#cc017) |
| [2.20.3](#v2203) | Failures print a one-line header and an indented block per check, in place of the ASCII banner; an agent skill for coding agents | [Getting started](getting-started.md#2-watch-it-reject-something) · [With AI coding agents](guides/ai-agents.md#tell-the-agent) |
| [2.20.1](#v2201) | `--ai-attribution-only` checks a pull request description against your AI policy; JSON lists the AI tools found; more AI marks recognised | [Checking a pull request description](guides/policies.md#checking-a-pull-request-description) · [CC013](rules.md#cc013) |
Expand Down Expand Up @@ -40,6 +41,16 @@ page that documents it.
| [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Across an organization](guides/organization.md) |
| [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) |

## v2.21.0 (2026-11-16) { #v2210 }

### Added

* CC501 checks that a pull request description ticks exactly one of the AI declaration checkboxes listed in `[pull_request] ai_declaration_checkboxes`. ([CC501](rules.md#cc501), [#699](https://github.com/commit-check/commit-check/pull/699))

### Fixed

* CC014's advice names the trailer to add when the message has no blank line before the AI mark. ([CC014](rules.md#cc014), [#696](https://github.com/commit-check/commit-check/pull/696))

## v2.20.5 (2026-11-11) { #v2205 }

### Changed
Expand Down
2 changes: 1 addition & 1 deletion docs/compare/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Replace the hook:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-message
```
Expand Down
7 changes: 4 additions & 3 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,10 +87,10 @@ $ echo "feat: add streaming support" | commit-check -m
```

It is a warning, not an error: the exit code and the JSON on stdout do not
change. The top-level `warn` list and the GitHub App's
change. The top-level `warn` list and the
[`[jira]`](guides/github-app.md#jira-ticket-references) and
[`[pull_request]`](#pull-requests-every-commit-or-the-squash-message) sections
are read elsewhere and are not reported. The Python API reads no file at all
are not checked for unknown settings. The Python API reads no file at all
(it takes a `config` dict), and the MCP server loads the file itself without
reporting unknown settings.

Expand Down Expand Up @@ -274,7 +274,7 @@ Used from a hook definition, with no config file anywhere in the repository:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-message
args:
Expand Down Expand Up @@ -415,3 +415,4 @@ the same thing twice, so read the description rather than the cell:
| files | prohibited_patterns | list[str] | [] (empty list) | fnmatch patterns a committed path may not match, e.g. `["*.pem", ".env", "id_rsa*"]`. A bare pattern also matches the file name at any depth. Matching is case-sensitive on every platform, like git pathspecs. Empty disables the rule. |
| files | max_path_length | int | 0 (disabled) | Longest a committed file path may be, in characters. `0` disables the rule. |
| pull_request | check | str | "commits" | GitHub App only. `"commits"` checks every commit of a pull request on its own; `"squash"` checks the one message a squash merge would land, built from the repository's merge settings. See [Pull requests](#pull-requests-every-commit-or-the-squash-message). |
| pull_request | ai_declaration_checkboxes | list[str] | [] (rule off) | The texts of the AI declaration boxes in the pull request template, one per box. When set, a pull request description checked with `--ai-attribution-only` must tick exactly one of them; see [CC501](rules.md#cc501). Read by the CLI, the Action and the App. |
2 changes: 1 addition & 1 deletion docs/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ pushed:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-no-force-push
stages: [pre-push]
Expand Down
3 changes: 2 additions & 1 deletion docs/guides/github-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,8 @@ push or pull request, in the same four places: `cchk.toml`, `commit-check.toml`,
applies, precedence included; the `[push]`, `[files]` and `[tag]` sections are
read but have nothing to act on here. Nothing is App-specific to set apart
from `[pull_request]` (above) and `[jira]` (below); the CLI and the Action ignore
them.
them, except `[pull_request] ai_declaration_checkboxes`
([CC501](../rules.md#cc501)), which all three read.

[`inherit_from`](organization.md) works, and a `github:` target is fetched with
the App's own credentials, so a shared config in a private `.github` repository
Expand Down
36 changes: 36 additions & 0 deletions docs/guides/policies.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,42 @@ $ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only --form
["Devin"]
```

### Requiring the template's AI declaration

Many pull request templates ask the author to tick one of two boxes, such as
"No AI tools were used" or "If AI tools were used, I have disclosed which
ones". Django, statsmodels and Frigate each run their own script in CI to make
sure one of them is ticked. List the boxes' texts and
[CC501](../rules.md#cc501) does that check:

```toml title="cchk.toml"
[pull_request]
ai_declaration_checkboxes = ["No AI tools were used", "If AI tools were used"]
```

```console
$ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only
✖ Commit rejected by Commit Check · 1 check failed

✖ CC501 ai-declaration failed: - [ ] **No AI tools were used** in preparing this PR. (+1 more line)
No AI declaration box is ticked
Suggest: Tick the box that applies: "No AI tools were used" or "If AI tools were used"
Docs: https://commit-check.com/rules/#cc501
```

Each option is the start of a box's text, so `**If AI tools were used**, I
have disclosed which ones.` matches `If AI tools were used`. The rule fails
when no box is ticked, when both are, and when the description has no boxes
at all. Boxes inside an HTML comment are ignored, so instructions in the
template do not count as an answer.

It works on its own: `ai_attribution` can stay at `"ignore"`. In the
[Action](github-actions.md), turn on `pr-body-ai-attribution: true`; in the
[GitHub App](github-app.md), set `body_ai_attribution = true` under
`[pull_request]`. The App checks the description again whenever it is
edited; the Action does too once its workflow lists `edited` under
`pull_request` `types`.

### Asking for disclosure instead

Most projects that allow AI assistance ask to be told about it.
Expand Down
6 changes: 3 additions & 3 deletions docs/guides/pre-commit.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Add Commit Check to `.pre-commit-config.yaml`:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-message
- id: check-branch
Expand Down Expand Up @@ -68,7 +68,7 @@ Options can be passed as hook arguments, which keeps everything in one file:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-message
args:
Expand All @@ -90,7 +90,7 @@ colon, and lets the commit through:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.20.5
rev: v2.21.0
hooks:
- id: check-message
args: [--fix]
Expand Down
72 changes: 72 additions & 0 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -1141,3 +1141,75 @@ git tag v1.2.3-rc.1

* `tag.regex` — the pattern a tag name must match. An empty value disables the
pattern match.

## Pull request rules

### ai-declaration (CC501) { #cc501 }

**What it does**

Checks that a pull request description answers the AI question its template
asks, often under an "AI disclosure" heading: exactly one of the boxes listed in
`pull_request.ai_declaration_checkboxes` is ticked. It runs only under `--ai-attribution-only`, the mode that reads a
pull request description, and only when that option is set.

A box is a task-list item (`- [ ]`, `* [x]`, `1. [X]`) whose text starts with
one of the options, compared without case, emphasis or extra spaces, on whole
words. `- [ ] **No AI tools were used** in preparing this PR.` is a box for
the option `No AI tools were used`. Boxes inside HTML comments or code blocks
are not read, so the template's own instructions never count as an answer.
When two options both fit a box, the longer one wins.

The rule fails when:

* no box is ticked,
* more than one option is ticked, or
* the description has no box at all, as when the template was deleted.

Authors in `commit.ignore_authors` are skipped, so a bot's pull request does
not need the declaration.

**Why is this bad?**

A project that asks contributors to declare AI use can only rely on the answer
if it is there. An unticked box reads the same as "I did not look", and a
deleted template the same as a missing answer. Projects that ask the question
end up checking the description in CI, each with its own script.

**Example**

```toml title="cchk.toml"
[pull_request]
ai_declaration_checkboxes = ["No AI tools were used", "If AI tools were used"]
```

```markdown
#### AI Assistance Disclosure (REQUIRED)
- [ ] **No AI tools were used** in preparing this PR.
- [ ] **If AI tools were used**, I have disclosed which ones.
```

```console
$ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only
✖ Commit rejected by Commit Check · 1 check failed

✖ CC501 ai-declaration failed: - [ ] **No AI tools were used** in preparing this PR. (+1 more line)
No AI declaration box is ticked
Suggest: Tick the box that applies: "No AI tools were used" or "If AI tools were used"
Docs: https://commit-check.com/rules/#cc501
```

Use instead:

```markdown
- [x] **No AI tools were used** in preparing this PR.
- [ ] **If AI tools were used**, I have disclosed which ones.
```

**Options**

* `pull_request.ai_declaration_checkboxes` — the text each box starts with, one
string per box. Unset (the default) turns the rule off. The
[Action](guides/github-actions.md) runs it with `pr-body-ai-attribution: true`
and the [GitHub App](guides/github-app.md) with
`[pull_request] body_ai_attribution = true`.