diff --git a/docs/assets/extra.css b/docs/assets/extra.css index 8f882e6..76463ae 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -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. */ diff --git a/docs/configuration.md b/docs/configuration.md index 5a5f683..07df041 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 | @@ -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 | @@ -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} diff --git a/docs/example.md b/docs/example.md index 3970a48..1478f33 100644 --- a/docs/example.md +++ b/docs/example.md @@ -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 @@ -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 06ccd8a..621624a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 @@ -163,7 +160,7 @@ belongs:
-- :lucide-git-commit-horizontal:{ .lg .middle } __Before the commit lands__ +- :lucide-git-commit-horizontal: __Before the commit lands__ --- @@ -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__ --- diff --git a/docs/guides/github-actions.md b/docs/guides/github-actions.md index 758a9ac..ac6cc67 100644 --- a/docs/guides/github-actions.md +++ b/docs/guides/github-actions.md @@ -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 @@ -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. @@ -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 diff --git a/docs/guides/github-app.md b/docs/guides/github-app.md index 303afc9..9882ed2 100644 --- a/docs/guides/github-app.md +++ b/docs/guides/github-app.md @@ -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. @@ -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, @@ -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 @@ -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 diff --git a/docs/guides/other-ci.md b/docs/guides/other-ci.md index 81d804c..fab235d 100644 --- a/docs/guides/other-ci.md +++ b/docs/guides/other-ci.md @@ -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. diff --git a/docs/index.md b/docs/index.md index 3613ae2..104850c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. diff --git a/docs/overrides/landing.html b/docs/overrides/landing.html index 96fe3b3..cbd8184 100644 --- a/docs/overrides/landing.html +++ b/docs/overrides/landing.html @@ -16,7 +16,18 @@ {% 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 %} +
{{ page.content }} diff --git a/docs/stylesheets/landing.css b/docs/stylesheets/landing.css index f8fee75..4818d90 100644 --- a/docs/stylesheets/landing.css +++ b/docs/stylesheets/landing.css @@ -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;