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
20 changes: 20 additions & 0 deletions docs/assets/extra.css
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,26 @@ body {
letter-spacing: -0.01em;
}

/* Code ----------------------------------------------------------------------
JetBrains Mono draws `!=` as ≠ and `->` as an arrow unless ligatures are
off. Sumi turns them off for every code element, but its `font` shorthand
on `.sumi-prose pre` resets that, so a reader copying a block by eye sees a
character the shell does not have. Set it again after the shorthand. */
.sumi-prose pre,
.sumi-prose pre code {
font-variant-ligatures: none;
font-feature-settings: "liga" 0, "calt" 0;
}

/* Sumi lets inline code break anywhere, which in a table also shrinks the
column to one character: an auto-sized table then splits `message` into
`messag` and `e`. break-word still wraps a value too long for its cell, but
leaves the column wide enough for each word. */
.sumi-prose td code,
.sumi-prose th code {
overflow-wrap: break-word;
}

/* Buttons -------------------------------------------------------------------
A primary button is Signal Blue with Ink text: white on this blue is 3.1:1,
under the 4.5:1 a button label needs; Ink on it is 5.9:1. */
Expand Down
30 changes: 30 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,17 @@ the same thing twice, so read the description rather than the default:
- `require_rebase_target` unset is the one case where the check really does not
run — there is no branch to compare against.

### Top level

These two sit above every section, at the top of the file.

| Option | Type | Default | Description |
|---|---|---|---|
| `inherit_from` | str | "" (none) | A shared config to start from: a path, a URL, or `github:owner/repo:path`. This file's own settings override it. See [Inheriting a shared config](#inheriting-a-shared-config) and [Across an organization](guides/organization.md). |
| `warn` | list[str] | [] (nothing warned) | Checks or rule IDs to report without failing, e.g. `["branch", "CC003"]`. See [Report a rule without enforcing it](#report-a-rule-without-enforcing-it). |

{.fields}

### `[commit]`

| Option | Type | Default | Description |
Expand Down Expand Up @@ -408,6 +419,10 @@ the same thing twice, so read the description rather than the default:

{.fields}

The GitHub App also reads `require_verified` (bool, default `false`) in this
section: every commit has to show **Verified** on GitHub. The CLI and the
Action do not check signatures; see [Verified commits](guides/github-app.md#verified-commits).

### `[branch]`

| Option | Type | Default | Description |
Expand Down Expand Up @@ -453,5 +468,20 @@ the same thing twice, so read the description rather than the default:
|---|---|---|---|
| `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). |
| `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. |
| `body_ai_attribution` | bool | false | GitHub App only. Check the pull request description against the AI rules (CC013 to CC016), and its AI declaration boxes when `ai_declaration_checkboxes` is set. The Action's `pr-body-ai-attribution` input does the same. See [AI-written pull requests](guides/github-app.md#ai-written-pull-requests). |
| `ai_label` | bool or str | false | GitHub App only. Label a pull request an AI tool wrote any of: `true` for `ai-assisted`, or the label's name. Labels are only added, never removed. |

{.fields}

### `[jira]`

GitHub App only; the CLI and the Action ignore the section. See
[Jira ticket references](guides/github-app.md#jira-ticket-references).

| Option | Type | Default | Description |
|---|---|---|---|
| `required` | bool | false | Every commit message, or the squash message, has to reference a Jira ticket. |
| `pattern` | str | `[A-Z]+-\d+` | Regex for a ticket reference, e.g. `"PROJ-\\d+"` in TOML for one project. |
| `suggestion` | str | "" (built-in text) | The fix shown when the reference is missing. |

{.fields}
20 changes: 19 additions & 1 deletion docs/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,23 @@ message file to rewrite, so with stdin or `--rev` it is a usage error, and
`--dry-run` rewrites nothing. In the `commit-msg` hook it is one argument:
see [Fixing the message instead of rejecting it](guides/pre-commit.md#fixing-the-message-instead-of-rejecting-it).

### Checking a pull request title

With squash merges the pull request title becomes the commit, so check it the
same way. `--pr-title` reads the title from stdin and runs the message rules a
one-line title can meet: every `--message` rule except a body
([CC011](rules.md#cc011)), a sign-off ([CC012](rules.md#cc012)) and an AI
author ([CC017](rules.md#cc017)).

```console
$ gh pr view 42 --json title -q .title | commit-check --pr-title --compact
[FAIL] CC001 message: Add GitLab support
```

The [GitHub Action](guides/github-actions.md#inputs) does this with
`pr-title: true`; on GitLab and Bitbucket see
[Merge request title and description](guides/other-ci.md#merge-request-title-and-description).

## Checking the branch

```console
Expand Down Expand Up @@ -323,7 +340,8 @@ For any other skip, such as a merge subject, `reason` is empty.
On a `pull_request` checkout, `HEAD` is the synthetic merge commit — so a
bare `commit-check -m` exits `0` with every subject rule skipped. The
notice makes that visible; the fix is to check what you actually mean:
the PR title piped on stdin, or each branch commit via `--rev` as above.
the PR title piped into `commit-check --pr-title`, or each branch commit
via `--rev` as above.

### Reading the JSON

Expand Down
11 changes: 4 additions & 7 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,17 +132,14 @@ repository root — or in `.github/` — to make the policy explicit:
```toml title="cchk.toml"
[commit]
conventional_commits = true
subject_imperative = true # (1)
subject_imperative = true # off by default: rejects "fixed a bug", wants "fix a bug"
subject_max_length = 72
allow_wip_commits = false # (2)
allow_wip_commits = false # allow_* says what is permitted; false enforces

[branch]
conventional_branch = true
```

1. Off by default. Turning it on rejects `fixed a bug` in favour of `fix a bug`.
2. `allow_*` options describe what is *permitted*. Set to `false` to enforce.

Run it again and the new rules apply:

```console
Expand All @@ -163,7 +160,7 @@ belongs:

<div class="grid cards" markdown>

- :lucide-git-commit-horizontal:{ .lg .middle } __Before the commit lands__
- :lucide-git-commit-horizontal: __Before the commit lands__

---

Expand All @@ -172,7 +169,7 @@ belongs:

[:lucide-arrow-right: Pre-commit hook](guides/integrations.md#as-a-pre-commit-hook)

- :brand-github:{ .lg .middle } __On every pull request__
- :brand-github: __On every pull request__

---

Expand Down
22 changes: 13 additions & 9 deletions docs/guides/github-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
- uses: actions/checkout@v7
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0 # (1)
fetch-depth: 0 # recommended, see below
- uses: commit-check/commit-check-action@v2
with:
message: true
Expand All @@ -31,10 +31,10 @@ jobs:
author-email: true
```

1. Recommended, not required: the Action then reads the pull request's
commits from the clone. With a shallow clone it lists them through the
GitHub API instead (up to 250), and if it cannot, it warns and checks the
head commit alone.
`fetch-depth: 0` is recommended, not required: the Action then reads the pull
request's commits from the clone. With a shallow clone it lists them through
the GitHub API instead (up to 250), and if it cannot, it warns and checks the
head commit alone.

The Action reads the same `cchk.toml` as the CLI, so a repository that already
has one needs no Action-specific configuration.
Expand All @@ -60,13 +60,17 @@ has one needs no Action-specific configuration.
| `author-name` | `false` | Check each commit's author name |
| `author-email` | `false` | Check each commit's author email |
| `files` | `false` | Check the files each commit changes against the [`[files]` rules](../rules.md#push-rules) of `cchk.toml` (size, prohibited paths, path length). Needs `fetch-depth: 0`: a commit the clone holds without its parent is skipped. Since v2.24.0 |
| `pr-title` | `false` | Check the pull request title against Conventional Commits, the one that matters for squash merges. Pull request events only |
| `pr-comments` | `false` | Post the report as a pull request comment, edited in place on later runs |
| `pr-title` | `false` | Check the pull request title, the one that matters for squash merges, against the message rules a one-line title can meet: every `message` rule except a body (CC011), a sign-off (CC012) and an AI author (CC017). Pull request events only |
| `message-ai-attribution` | `false` | Check every commit against the [AI rules](policies.md#checking-ai-attribution-and-nothing-else) of `cchk.toml` (`ai_attribution`) only, author included, without the format rules. Takes the place of `message` |
| `pr-body-ai-attribution` | `false` | Check the [pull request description](policies.md#checking-a-pull-request-description) against the AI rules of `cchk.toml`, and its [AI declaration boxes](../rules.md#cc501) when `[pull_request] ai_declaration_checkboxes` is set. Pull request events only |
| `ai-label` | `false` | Label the pull request when an AI tool wrote any of it (a commit, the description, or an agent's app that opened it): `true` for `ai-assisted`, or the label's name. Labels are only added, never removed. Needs `pull-requests: write`; skipped on fork pull requests under `pull_request` |
| `pr-comments` | `false` | Post the report as a pull request comment, edited in place on later runs. Needs `pull-requests: write`; skipped on fork pull requests |
| `job-summary` | `true` | Write the report to the job summary |
| `dry-run` | `false` | Report failures as warnings and always exit `0` |

`pull_request` does not fire when a title is edited. With `pr-title: true`,
add `types: [opened, synchronize, reopened, edited]` to re-check a renamed pull
`pull_request` does not fire when a title or description is edited. With
`pr-title` or `pr-body-ai-attribution`, add
`types: [opened, synchronize, reopened, edited]` to re-check an edited pull
request.

The Action also sets a `result` output: the check results as JSON, read with
Expand Down
62 changes: 58 additions & 4 deletions docs/guides/github-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,11 @@ way everywhere:

### Which rules

The App runs the commit message, author and branch rules — [CC001–CC016](../rules.md#commit-message-rules),
The App runs the commit message, author and branch rules — [CC001–CC017](../rules.md#commit-message-rules),
[CC101–CC102](../rules.md#author-rules) and [CC201–CC202](../rules.md#branch-rules) —
with the commit's own branch as the branch under test. One thing it does not
with the commit's own branch as the branch under test, and, when it checks the
pull request description, the AI declaration rule [CC501](../rules.md#cc501)
(see [AI-written pull requests](#ai-written-pull-requests)). One thing it does not
do: the push, file and tag rules ([CC301–CC304](../rules.md#push-rules),
[CC401](../rules.md#tag-rules)) run where a push or a tag happens, in the
[pre-commit hooks](pre-commit.md) and the CLI.
Expand Down Expand Up @@ -82,6 +84,35 @@ repository's merge settings, pull request number included. Editing the title or
description re-runs it. The [configuration page](../configuration.md#pull-requests-every-commit-or-the-squash-message)
has the table of what is checked under each merge setting.

### AI-written pull requests

Two settings for pull requests an AI tool helped write. Both read the same
[`ai_attribution`](policies.md#ai-attribution) rules and the same detection as
the commit checks:

```toml title="cchk.toml"
[pull_request]
body_ai_attribution = true # check the description against the AI rules
ai_label = true # label AI-written pull requests "ai-assisted"
# ai_label = "AI generated" # or a label name of your own
```

- `body_ai_attribution = true` checks the pull request description with the
AI rules only (CC013 to CC016): under `forbid` an AI footer such as
"Generated with Claude Code" fails, under `disclose` it has to be disclosed.
The result joins the head commit's check as a `PR description` row, and
editing the description re-runs it. With `ai_declaration_checkboxes` set,
the description also has to tick exactly one of the template's AI
declaration boxes ([CC501](../rules.md#cc501)).
- `ai_label` adds the label when an AI tool wrote any of the pull request: a
commit message or author, the description, or an AI agent's app that opened
it (Copilot coding agent, Devin, Jules, Codex, ...). It does not depend on
the policy, so `ai_attribution = "ignore"` with a label marks pull requests
without ever failing one. The label is only added, never removed, and is
created if the repository does not have it. Labelling needs the App's
**Pull requests: write** permission; an installation approved before the App
asked for it has to accept the new permission first.

### Bots, re-runs, and commits checked twice

- Commits by bots (any author whose name ends in `[bot]`: dependabot,
Expand All @@ -103,8 +134,8 @@ push or pull request, in the same four places: `cchk.toml`, `commit-check.toml`,
[configuration page](../configuration.md) that belongs to a rule the App runs
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, except `[pull_request] ai_declaration_checkboxes`
from `[pull_request]` (above), `[jira]` and `[commit] require_verified` (below);
the CLI and the Action ignore 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
Expand Down Expand Up @@ -159,6 +190,29 @@ suggestion = "Add the ticket, e.g. PROJ-123"
It reports as `JIRA jira-ticket` in the same table as the other rules. It
checks the reference's shape, not whether the ticket exists.

### Verified commits

The other App-side check. With `require_verified = true` under `[commit]`,
every commit has to show **Verified** on GitHub: signed with a GPG, SSH or
S/MIME key that is on the signer's GitHub account.

```toml title="cchk.toml"
[commit]
require_verified = true
```

It reports as `VERIFIED verified-commit`, and a failure says why GitHub did not
verify the commit (not signed, unknown key, unverified email, ...) with the
command that re-signs it. The verdict is GitHub's own, read from the API, so
nobody gives the App public keys and the result always matches the badge.
Unlike GitHub's "Require signed commits" branch rule, which only refuses the
push, the check names each commit that is not verified and says why.

- Commits by bots the App skips (dependabot, renovate, ...) are not checked.
- In squash mode the branch commits do not land, and GitHub signs the squash
commit it creates, so nothing is checked.
- The CLI and the Action cannot read GitHub's verdict and ignore this setting.

## Enforcing it

The App marks a commit; it cannot refuse a push. What keeps a violating change
Expand Down
1 change: 1 addition & 0 deletions docs/guides/other-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ lines to the `script`, before the commit loop (its `exit` ends the script):
```yaml
- test "$CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED" != "true" || { echo "The description is over 2700 characters; GitLab passed only part of it"; exit 1; }
```

- Editing the title or description does not start a pipeline. Run the
pipeline again from the merge request's **Pipelines** tab after an edit.

Expand Down
5 changes: 4 additions & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
---
hide:
- navigation
- toc
template: landing.html
# Sumi gives a landing.html page the "landing" layout, which has no sidebar and
# so no menu button on a phone. "docs" keeps the button; landing.html draws
# the page itself and shows the sidebar only as the phone drawer.
layout: docs
title: Commit Check
seo_title: Commit Check — Commit policy as code for teams and AI agents
description: Commit policy as code for teams and AI agents. Messages, branches, authors and AI attribution, checked from your commit hook to every pull request.
Expand Down
11 changes: 11 additions & 0 deletions docs/overrides/landing.html
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,18 @@
<link rel="stylesheet" href="{{ 'stylesheets/landing.css' | url }}">
{% endblock %}

{#
The site navigation as the phone drawer, the same one every other page has.
Sumi shows its menu button only when the page has a sidebar, so the page
keeps its navigation (no `hide: navigation`) and renders the sidebar here;
landing.css hides it on wide screens, where the landing takes the full width.
#}
{% block layout %}
<aside class="sumi-sidebar cc-landing-drawer" id="sumi-sidebar" aria-label="{{ t('navigation') }}">
<div class="sumi-sidebar-inner">
<nav class="sumi-nav">{{ m.nav_tree(nav.items, 1) }}</nav>
</div>
</aside>
<main class="sumi-main cc-landing" id="content">
<div class="md-typeset" data-pagefind-body>
{{ page.content }}
Expand Down
9 changes: 9 additions & 0 deletions docs/stylesheets/landing.css
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,15 @@
overflow-x: clip;
}

/* The navigation drawer (see landing.html). Sumi turns `.sumi-sidebar` into
the slide-in drawer at 920px and below; above that the landing has no
sidebar, so it is not shown at all. */
@media screen and (min-width: 921px) {
.cc-landing-drawer {
display: none;
}
}

.cc-landing > .md-typeset {
max-width: var(--cc-page-w, 1220px);
margin: 0 auto;
Expand Down