From 22575f0cc43ca7a499e10a525812b1965f4f9018 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 27 Sep 2026 19:02:41 +0300 Subject: [PATCH] docs: rebuild the README around what a new user needs first The first screen was a year-old "What's New in v2" notice, the eight inputs took a section each, and the job summary was reproduced four times, one per status, about 170 lines. - The header matches the org profile and the core README: the v4 banner (light and dark), the site's line, five badges in the brand colors and links to the docs, the CLI, the App and the MCP server. - The inputs are one table. - One failing job summary stays, as rendered; the passed, warned and skipped variants are a sentence each. - Runner requirements and the fork and Dependabot notes fold into
; the v2 breaking changes become a link to the v2.0.0 release notes. - The pre-commit link in the comparison table pointed at an anchor the core README never had; it now goes to the pre-commit guide. - The snippet under "Badging" was this repository's own CI status badge, so a user who pasted it advertised our build, not theirs. It is now the commit-check badge the core README and the site use. used-by.yml rewrites the "Used by" badge every week from its own inputs, so they change with it: color 2c9ccd, and the Ink label color carried in badge-logo, which the action appends to the query string as it is. Running used-by v0.1.5's badge generator against the new README reproduces the line byte for byte, so the job has nothing to change. --- .github/workflows/used-by.yml | 6 + README.md | 598 ++++++++++------------------------ 2 files changed, 179 insertions(+), 425 deletions(-) diff --git a/.github/workflows/used-by.yml b/.github/workflows/used-by.yml index d45bfbb3..0a62b57e 100644 --- a/.github/workflows/used-by.yml +++ b/.github/workflows/used-by.yml @@ -19,6 +19,12 @@ jobs: with: repo: '${{ github.repository }}' update-badge: 'true' + # used-by appends these to the shields.io query string as they are, + # which is how the logo also carries the brand's label color. The + # badge it writes must match README.md's byte for byte, or this job + # opens a pull request every week that only restyles it. + badge-color: '2c9ccd' + badge-logo: 'github&logoColor=white&labelColor=0b1620' - name: Create Pull Request uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 diff --git a/README.md b/README.md index bc972c29..2a6468d9 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,34 @@ -# Commit-Check GitHub Action +
-![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/commit-check/commit-check-action?color=blue) -[![Used by](https://img.shields.io/static/v1?label=Used%20by&message=167&color=informational&logo=slickpic)](https://github.com/commit-check/commit-check-action/network/dependents) -[![GitHub marketplace](https://img.shields.io/badge/Marketplace-commit--check--action-blue)](https://github.com/marketplace/actions/commit-check-action) -[![commit-check](https://img.shields.io/badge/commit--check-enabled-2c9ccd?labelColor=0b1620&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI%2bPHBhdGggZD0iTTIxIDM0TDMwIDQzTDQ3IDIyIiBmaWxsPSJub25lIiBzdHJva2U9IiMyQzlDQ0QiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8%2bPGNpcmNsZSBjeD0iMjEiIGN5PSIzNCIgcj0iNyIgZmlsbD0iIzBCMTYyMCIgc3Ryb2tlPSIjMkM5Q0NEIiBzdHJva2Utd2lkdGg9IjUiLz48L3N2Zz4K)](https://commit-check.com) -[![slsa-badge](https://slsa.dev/images/gh-badge-level3.svg?color=blue)](https://github.com/commit-check/commit-check-action/blob/main/action.yml#L84-L94) -[![codecov](https://codecov.io/gh/commit-check/commit-check-action/graph/badge.svg?token=QHUDSMJGS7)](https://codecov.io/gh/commit-check/commit-check-action) - -A GitHub Action for checking commit message formatting, branch naming, committer name, email, commit signoff, and more. + + + Commit Check + -## What's New in v2 +**Catch bad commits before they merge โ€” on every pull request.** -> [!IMPORTANT] -> This v2 release introduces several ๐Ÿšจ**breaking changes**. Please review the [Breaking Changes](#breaking-changes) section carefully before upgrading. +[![Release](https://img.shields.io/github/v/release/commit-check/commit-check-action?labelColor=0b1620&color=2c9ccd&label=release)](https://github.com/commit-check/commit-check-action/releases) +[![Used by](https://img.shields.io/static/v1?label=Used%20by&message=167&color=2c9ccd&logo=github&logoColor=white&labelColor=0b1620)](https://github.com/commit-check/commit-check-action/network/dependents) +[![Marketplace](https://img.shields.io/badge/Marketplace-commit--check--action-2c9ccd?labelColor=0b1620&logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/commit-check-action) +[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://github.com/commit-check/commit-check-action/blob/main/action.yml#L84-L94) +[![Coverage](https://img.shields.io/codecov/c/github/commit-check/commit-check-action?labelColor=0b1620&color=2c9ccd&label=coverage)](https://codecov.io/gh/commit-check/commit-check-action) -### Breaking Changes +[Docs](https://commit-check.com/guides/github-actions/) ยท +[Rules](https://commit-check.com/rules/) ยท +[CLI](https://github.com/commit-check/commit-check) ยท +[GitHub App](https://github.com/apps/commit-check) ยท +[MCP server](https://github.com/commit-check/commit-check-mcp) -- Removed support for `commit-signoff`, `merge-base`, and `imperative` inputs โ€” now configured via `commit-check.toml` or `cchk.toml`. -- Deprecated `.commit-check.yml` in favor of `commit-check.toml` or `cchk.toml`. -- Changed default values of `author-name` and `author-email` inputs to `false` to align with the default behavior in commit-check. -- Upgraded core dependency [`commit-check`](https://github.com/commit-check/commit-check) to [**v2.0.0**](https://github.com/commit-check/commit-check/releases/tag/v2.0.0). +
-## Table of Contents - -* [Usage](#usage) -* [Action, pre-commit hook, or GitHub App โ€” which to use?](#action-pre-commit-hook-or-github-app--which-to-use) -* [Optional Inputs](#optional-inputs) -* [GitHub Action Job Summary](#github-action-job-summary) -* [GitHub Pull Request Comments](#github-pull-request-comments) -* [Advanced Configuration](#advanced-configuration) -* [Fork Pull Requests](docs/fork-pr-comments.md) -* [Badging Your Repository](#badging-your-repository) -* [Versioning](#versioning) +The GitHub Action for [Commit Check](https://github.com/commit-check/commit-check). +It checks every commit of a pull request โ€” message, branch, author, and +optionally the PR title โ€” against your `cchk.toml`, and reports the result in +the job summary, as annotations on the diff and, if you want, as a PR comment. ## Usage -Create a new GitHub Actions workflow in your project, e.g. at [.github/workflows/commit-check.yml](.github/workflows/commit-check.yml) +Add a workflow, e.g. `.github/workflows/commit-check.yml`: ```yaml name: Commit Check @@ -67,173 +60,38 @@ jobs: pr-comments: true ``` -> [!WARNING] -> Without `fetch-depth: 0` the action still runs, but it cannot see the pull -> request's commits. It posts `::warning title=commit-check::Could not list the -> pull request's commits (is actions/checkout using fetch-depth: 0?); only HEAD -> was checked` and checks only the synthetic merge commit โ€” whose subject -> `Merge into ` passes the default rules โ€” so a shallow clone makes -> every PR look green. Author checks are skipped (`โŠ˜`) for the same reason. On +> [!IMPORTANT] +> Keep `fetch-depth: 0`. A shallow clone holds only GitHub's merge commit, +> whose `Merge into ` subject passes the default rules, so every +> pull request would look green; the action warns when it happens. On > `pull_request_target`, also check out `refs/pull//merge`. -> [!NOTE] -> This action supports running on Linux, macOS, and Windows (`ubuntu-latest`, `macos-latest`, `windows-latest`). - -### Runner requirements - -The action is a composite step and uses what the runner already has: - -- **Python 3.10 or newer** on `PATH` (`python3`, or `python` on Windows). No - `setup-python` step is needed on GitHub-hosted runners. Everything the action - installs goes under `$RUNNER_TEMP`, never into your checkout. -- **`gh` CLI** โ€” used to verify the build-provenance attestation of the - `commit-check` wheel before installing it. Present on GitHub-hosted images; - install it on self-hosted runners or the attestation step fails. - Only the `commit-check` wheel is attested; PyGithub and the transitive - dependencies are pinned by `requirements.txt` but not verified. -- **Network access to PyPI and `api.github.com`** โ€” the pinned wheels are - downloaded once per run and the attestation is fetched from GitHub. -- **`git`** on `PATH`, and a checkout with `fetch-depth: 0` (see above). - -There is currently no input to skip attestation verification. - -## Action, pre-commit hook, or GitHub App โ€” which to use? - -All three run the same `commit-check` engine against the same -`commit-check.toml` / `cchk.toml`; they differ in where they run and what they -can see. - -| | GitHub Action (this repo) | [pre-commit hook](https://github.com/commit-check/commit-check#use-with-pre-commit) | [Commit Check GitHub App](https://github.com/apps/commit-check) | -|---|---|---|---| -| **Where it runs** | In your workflow, on the runner, after the push | On the contributor's machine, at `git commit` / `git push` | Hosted by commit-check; installed on the repository, no workflow file | -| **What it checks** | Every PR commit's message, plus the PR title, branch and author checks you enable; renders a job summary, annotations, a PR comment and the `result` output | Message (`commit-msg` stage), branch, author; tag, force-push and files (`pre-push`) โ€” one commit at a time, before it exists | Every commit of a push or pull request: message, branch, author (the PR title only in squash mode); reported as one **Commit Check** check run per commit | -| **When to pick it** | You want enforcement in CI that a contributor cannot skip, per-rule outputs for later steps, or you run on GitHub Enterprise Server / need `CCHK_*` overrides | You want the fastest feedback and to stop bad commits before they are pushed; pair it with the Action, since hooks are opt-in | You want zero YAML and no Actions minutes, or feedback on [fork pull requests](docs/fork-pr-comments.md) without the Action's read-only-token limits | - -Most teams pair the pre-commit hook (fast, local) with the Action (enforced): -the hook catches a bad message before it is pushed, and the Action is why CI -fails when a contributor did not install the hook. - -## Used By - -

- Apache - Apache   - discovery-unicamp - discovery-unicamp   - Texas Instruments - Texas Instruments   - OpenCADC - OpenCADC   - Extrawest - Extrawest   - Chainlift - Chainlift   - Mila - Mila   - RLinf - RLinf   - Collective - Collective   - cpp-linter - cpp-linter   - and many more. -

- -## Optional Inputs - -### `message` - -- **Description**: check git commit message following [Conventional Commits](https://www.conventionalcommits.org/). -- Default: `true` - -### `branch` - -- **Description**: check git branch name following [Conventional Branch](https://conventionalbranch.org/). -- Default: `true` - -### `author-name` - -- **Description**: check committer author name. -- Default: `false` - -### `author-email` - -- **Description**: check committer author email. -- Default: `false` +Runs on `ubuntu-latest`, `macos-latest` and `windows-latest`. Self-hosted +runners need a few tools โ€” see [Good to know](#good-to-know). -### `dry-run` +## Inputs -- **Description**: report failures (job summary, PR comment, and annotations - downgraded to warnings) but always exit 0, so the job never fails. -- Default: `false` - -### `job-summary` - -- **Description**: display job summary to the workflow run. -- Default: `true` - -### `pr-comments` - -- **Description**: post results to the pull request comments. -- Default: `false` - -> [!NOTE] -> `pr-comments` is disabled by default. -> -> PR comments are skipped for pull requests from forked repositories, whose -> `GITHUB_TOKEN` is read-only. Everything else still works there: the check -> status, the annotations and the job summary. See -> [Fork pull requests](docs/fork-pr-comments.md). -> -> **Dependabot pull requests** are not forks, but GitHub gives their -> `pull_request` runs a read-only `GITHUB_TOKEN` by default. The `permissions` -> key is honoured for them, so the `pull-requests: write` grant in the -> [usage example](#usage) is enough; without it the action logs a -> `::warning::` on the 403 and leaves the report in the job summary. Note that -> Actions secrets are not available in Dependabot-triggered runs. Adding -> `dependabot[bot]` to `ignore_authors` skips the checks for those PRs -> altogether. -> -> Note: write-access to pull-requests requires the `pull-requests: write` permission. -> See [usage example](#usage). - -### `pr-title` - -- **Description**: check pull request title following [Conventional Commits](https://www.conventionalcommits.org/). -- Default: `false` +| Input | Default | What it does | +|---|---|---| +| `message` | `true` | Check every commit message against [Conventional Commits](https://www.conventionalcommits.org/) | +| `branch` | `true` | Check the branch name against [Conventional Branch](https://conventionalbranch.org/) | +| `author-name` | `false` | Check each commit's author name | +| `author-email` | `false` | Check each commit's author email | +| `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. 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 | > [!TIP] -> This is especially useful for teams using **Squash & Merge**, where the PR title -> becomes the final commit message in the main branch. When enabled, the action -> validates the PR title against your Conventional Commits configuration, giving -> early feedback at PR time rather than after merge. -> -> `pr-title` works alongside `message` โ€” you can enable both to validate the PR -> title and individual commits, or just one depending on your workflow. -> -> This setting only applies to `pull_request` and `pull_request_target` events; -> it is silently ignored on `push` events. - -> [!IMPORTANT] -> By default, `pull_request` does **not** trigger on title changes. -> To validate the PR title immediately when updated, add `edited` to your -> workflow's event types: -> ```yaml -> on: -> pull_request: -> types: [opened, synchronize, reopened, edited] -> ``` -> Without `edited`, only the initial title (at PR creation) is validated. - -## Advanced Configuration - -The [Optional Inputs](#optional-inputs) above cover the most common settings. -For everything else (e.g., `subject-capitalized`, `require-signed-off-by`, -`ai-attribution`, custom `allow-commit-types`, etc.), you have two approaches: +> `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 request. -### Via Environment Variables +## Configuration -Set any `CCHK_*` environment variable in your workflow step โ€” no config file required: +The action reads the repository's `cchk.toml` or `commit-check.toml` โ€” the same +file the CLI and the pre-commit hook use. Any setting can also come from a +`CCHK_*` environment variable, no config file needed: ```yaml - uses: commit-check/commit-check-action@v2 @@ -244,29 +102,60 @@ Set any `CCHK_*` environment variable in your workflow step โ€” no config file r CCHK_ALLOW_COMMIT_TYPES: "feat,fix,docs,chore" ``` -All available environment variables follow the naming convention: -`CCHK_` + uppercase option name with underscores instead of hyphens. See the -[full mapping](https://commit-check.com/configuration/#environment-variables) -in the commit-check documentation. +Priority: inputs > environment variables > config file > defaults. A rule +listed under the config's top-level `warn` is reported in full but never fails +the run. Every key: [configuration reference](https://commit-check.com/configuration/). -### Via Configuration File +## What it looks like -Add a `commit-check.toml` or `cchk.toml` to the root of your repository. -Refer to the [configuration guide](https://commit-check.com/configuration/) -for all available options. +A failing run opens with a count and a table of only what failed โ€” each rule ID +links to its documentation, each commit to itself โ€” with the full tree one +click away: -> [!NOTE] -> Configuration priority: **CLI args > environment variables > config file > defaults**. -> The action itself doesn't set any CLI flags beyond those in -> [Optional Inputs](#optional-inputs), so env vars and config files are the -> recommended way to customize. +> **Commit Check** +> +> โŒ **2 of 4 checks failed** +> +> | Scope | Checked value | Failed checks | +> |---|---|---| +> | [Commit 2/2 (5584f46)](https://github.com/acme/widgets/commit/5584f462cc3c947b2ba8d3d1a5735571803ee159) | `bad msg` | [CC001 message](https://commit-check.com/rules/#cc001) | +> | Branch | `Feature/Add-Login` | [CC201 branch](https://commit-check.com/rules/#cc201) | +> +>
+> Show all 4 checks +> +> ```text +> Commit message +> โœ” PR title (feat: add login page) +> โœ” Commit 1/2 (d87faca) (feat: add login page) +> โœ– Commit 2/2 (5584f46) (1 failure) +> CC001 message +> value: bad msg +> The commit message should follow Conventional Commits. +> Suggest: Use (): +> Branch +> โœ– Branch (1 failure) +> CC201 branch +> value: Feature/Add-Login +> The branch should follow Conventional Branch. +> Suggest: Rename the branch to "feature/Add-Login" (git branch -m feature/Add-Login) +> Fix: feature/Add-Login +> ``` +> +>
+> +> _commit-check <version> ยท [Rules reference](https://commit-check.com/rules/)_ -The config's top-level `warn` reports a rule without failing the run โ€” see -[Warning Job Summary](#warning-job-summary) for what that looks like: +The rest follow the same layout: -```toml -warn = ["branch", "CC003"] -``` +- **Passed:** one line, `โœ… All 3 checks passed`, with the tree folded away. +- **Warned:** a rule under `warn` gets its own โš  row and counts as passed. +- **Skipped:** a run where nothing was validated โ€” typically a bot listed in + `ignore_authors` โ€” reads `โŠ˜`, never `โœ”`. + +The step log prints the same tree, plus one annotation per finding on the +Files changed tab. With `pr-comments: true` the same report is posted to the +pull request, and later runs edit that one comment instead of adding more. ## Outputs @@ -315,244 +204,103 @@ check outcomes (`rule_id`, `check`, `status`, `value`, `error`, `suggest`, `fix`, `docs_url`) exactly as produced by `commit-check --format json`, so downstream jobs can build their own reports or gate on individual rules. -## GitHub Action Job Summary - -By default, commit-check-action results are shown on the job summary page of the -workflow. The report below is reproduced as the action renders it, except that -its title is a heading in the real thing โ€” it is bold here so it stays out of -this page's table of contents โ€” and the footer names the version that actually -ran. - -### Success Job Summary - -Passing runs stay to one line, with the detail folded away: - -> **Commit Check** -> -> โœ… **All 3 checks passed** -> ->
-> Show all 3 checks -> -> ```text -> Commit message -> โœ” PR title (feat: add login page) -> โœ” Commit 1/2 (d87faca) (feat: add login page) -> Branch -> โœ” Branch (feature/add-login) -> ``` -> ->
-> -> _commit-check <version> ยท [Rules reference](https://commit-check.com/rules/)_ - -### Failure Job Summary - -Failures open with a count, then a table of only the scopes that failed โ€” every -rule ID links to its documentation, and every commit to itself โ€” with the full -tree still one click away: - -> **Commit Check** -> -> โŒ **2 of 4 checks failed** -> -> | Scope | Checked value | Failed checks | -> |---|---|---| -> | [Commit 2/2 (5584f46)](https://github.com/acme/widgets/commit/5584f462cc3c947b2ba8d3d1a5735571803ee159) | `bad msg` | [CC001 message](https://commit-check.com/rules/#cc001) | -> | Branch | `Feature/Add-Login` | [CC201 branch](https://commit-check.com/rules/#cc201) | -> ->
-> Show all 4 checks -> -> ```text -> Commit message -> โœ” PR title (feat: add login page) -> โœ” Commit 1/2 (d87faca) (feat: add login page) -> โœ– Commit 2/2 (5584f46) (1 failure) -> CC001 message -> value: bad msg -> The commit message should follow Conventional Commits. -> Suggest: Use (): -> Branch -> โœ– Branch (1 failure) -> CC201 branch -> value: Feature/Add-Login -> The branch should follow Conventional Branch. -> Suggest: Rename the branch to "feature/Add-Login" (git branch -m feature/Add-Login) -> Fix: feature/Add-Login -> ``` -> ->
-> -> _commit-check <version> ยท [Rules reference](https://commit-check.com/rules/)_ - -A scope is one thing that was checked โ€” a commit message, the branch, the author -โ€” not one rule evaluation, so the total matches the โœ”/โœ– lines you can count and -does not grow with the number of rules in your config. - -A commit scope names its commit by short hash, and the table row links to it, -so a reviewer can jump from a failed row straight to the offending commit. -`Fix:` is the corrected text commit-check proposes whenever the correction is -mechanical (a capitalised subject, a dropped WIP marker, a missing sign-off -trailer); when the suggestion is nothing more than "use the fix", only `Fix:` -is shown. - -The step log prints the same tree, then one annotation per finding โ€” shown in -the run summary and on the Files changed tab โ€” whose message carries the -commit, the checked value, the suggestion and the fix on separate lines: - -```text -::error title=CC001 message::Commit 2/2 (5584f46): The commit message should follow Conventional Commits.%0Avalue: bad msg%0ASuggest: Use (): -::error title=CC201 branch::Branch: The branch should follow Conventional Branch.%0Avalue: Feature/Add-Login%0ASuggest: Rename the branch to "feature/Add-Login" (git branch -m feature/Add-Login)%0AFix: feature/Add-Login -โœ– commit-check: 2 of 4 checks failed -``` - -The verdict is a plain line rather than another `::error`, so the run's error -count equals the number of findings. - -### Skipped Job Summary +## Action, pre-commit hook, or GitHub App? -Some runs validate nothing at all โ€” most commonly when the commit author is -listed in `ignore_authors`, which is how Dependabot and other bots are usually -exempted. Those runs report `โŠ˜`, never `โœ”`: - -> **Commit Check** -> -> โŠ˜ **All 3 checks skipped** โ€” nothing was validated -> ->
-> Show all 3 checks -> -> ```text -> Commit message -> โŠ˜ PR title (skipped) -> โŠ˜ Commit 1/1 (skipped) -> Branch -> โŠ˜ Branch (skipped) -> ``` -> ->
-> -> _commit-check <version> ยท [Rules reference](https://commit-check.com/rules/)_ - -A skipped scope carries no checked value, because nothing was examined. When -only some scopes skip, the verdict counts them separately โ€” -`โœ… **3 of 5 checks passed**, 2 skipped` โ€” so the headline never claims a pass -that did not happen. Failures still take precedence over skips. - -This needs commit-check 2.13.4 or newer, which reports `"status": "skip"` in -its JSON. Against an older engine every check is `pass` or `fail` as before, -and the report is unchanged. - -### Warning Job Summary - -A rule listed under the config's [top-level `warn`](#via-configuration-file) -still runs and is reported in full โ€” its own table row, its own entry in the -details block โ€” but it never fails the workflow. It counts toward "passed": - -> **Commit Check** -> -> โœ… **3 of 4 checks passed**, 1 warning -> -> | Scope | Checked value | Warnings | -> |---|---|---| -> | Branch | `jsmith/fix-x` | [CC201 branch](https://commit-check.com/rules/#cc201) | -> ->
-> Show all 4 checks -> -> ```text -> Commit message -> โœ” PR title (feat: add login page) -> โœ” Commit 1/2 (feat: add login page) -> Branch -> โš  Branch (1 warning) -> CC201 branch -> value: jsmith/fix-x -> The branch should follow Conventional Branch. -> Suggest: Use / with allowed types -> ``` -> ->
-> -> _commit-check <version> ยท [Rules reference](https://commit-check.com/rules/)_ - -A warned scope is marked `โš `, never `โœ–`, and a real failure elsewhere still -fails the run โ€” the verdict then reads `โŒ **N of M checks failed**, K -warnings` and both tables appear. In the step log, a warning becomes a -`::warning` annotation rather than `::error`, so it never counts toward the -run's error count. The [`result`](#result) output reports the run as -`"status": "warn"`, with exit code 0. +All three run the same `commit-check` engine against the same +`commit-check.toml` / `cchk.toml`; they differ in where they run and what they +can see. -This needs commit-check 2.17.0 or newer, which reports `"status": "warn"` in -its JSON. Against an older engine, or a config with no `warn` list, no check -can ever be a warning, and the report is unchanged. +| | GitHub Action (this repo) | [pre-commit hook](https://commit-check.com/guides/pre-commit/) | [Commit Check GitHub App](https://github.com/apps/commit-check) | +|---|---|---|---| +| **Where it runs** | In your workflow, on the runner, after the push | On the contributor's machine, at `git commit` / `git push` | Hosted by commit-check; installed on the repository, no workflow file | +| **What it checks** | Every PR commit's message, plus the PR title, branch and author checks you enable; renders a job summary, annotations, a PR comment and the `result` output | Message (`commit-msg` stage), branch, author; tag, force-push and files (`pre-push`) โ€” one commit at a time, before it exists | Every commit of a push or pull request: message, branch, author (the PR title only in squash mode); reported as one **Commit Check** check run per commit | +| **When to pick it** | You want enforcement in CI that a contributor cannot skip, per-rule outputs for later steps, or you run on GitHub Enterprise Server / need `CCHK_*` overrides | You want the fastest feedback and to stop bad commits before they are pushed; pair it with the Action, since hooks are opt-in | You want zero YAML and no Actions minutes, or feedback on [fork pull requests](docs/fork-pr-comments.md) without the Action's read-only-token limits | -## GitHub Pull Request Comments +Most teams pair the pre-commit hook (fast, local) with the Action (enforced): +the hook catches a bad message before it is pushed, and the Action is why CI +fails when a contributor did not install the hook. -With `pr-comments: true` the same report is posted as a pull request comment. -It is the same Markdown: the job summary and the comment are both rendered by -`render_report`, so the two surfaces cannot disagree. See -[Success Job Summary](#success-job-summary) and -[Failure Job Summary](#failure-job-summary) above for what it looks like. +## Used by -What differs is the lifecycle rather than the content: +

+ Apache + Apache   + discovery-unicamp + discovery-unicamp   + Texas Instruments + Texas Instruments   + OpenCADC + OpenCADC   + Extrawest + Extrawest   + Chainlift + Chainlift   + Mila + Mila   + RLinf + RLinf   + Collective + Collective   + cpp-linter + cpp-linter   + and many more. +

-- The comment is **edited in place** on later runs rather than added to, so a - pull request carries one Commit Check comment however many times CI runs. It - stays after the checks pass, showing the โœ… report rather than disappearing. -- Comments are identified by a hidden `` marker, so - reformatting the visible text does not orphan the previous one. If several - marked comments somehow exist, the newest is kept and the rest deleted. -- A comment from a version predating the marker is adopted rather than - duplicated โ€” but only when a bot posted it, since the older signal was just a - title prefix that a person could type by hand. +## Good to know -## Fork PR Comments +
+Runner requirements -When a pull request is opened from a **forked repository**, the `GITHUB_TOKEN` used by the -`pull_request` event has **read-only** permissions by design (GitHub security policy). -This means `pr-comments: true` cannot write a comment back to the PR. +The action is a composite step and uses what the runner already has: -By default, commit-check-action handles this gracefully: +- **Python 3.10 or newer** on `PATH` (`python3`, or `python` on Windows). No + `setup-python` step is needed on GitHub-hosted runners. Everything the action + installs goes under `$RUNNER_TEMP`, never into your checkout. +- **`gh` CLI** โ€” used to verify the build-provenance attestation of the + `commit-check` wheel before installing it. Present on GitHub-hosted images; + install it on self-hosted runners or the attestation step fails. + Only the `commit-check` wheel is attested; PyGithub and the transitive + dependencies are pinned by `requirements.txt` but not verified. +- **Network access to PyPI and `api.github.com`** โ€” the pinned wheels are + downloaded once per run and the attestation is fetched from GitHub. +- **`git`** on `PATH`, and a checkout with `fetch-depth: 0` (see above). -- PR comment writing is **skipped** with a `::warning::` message in the logs -- A **notice is added to the Job Summary** explaining why and how to fix it -- The commit checks themselves **still run normally** +There is currently no input to skip attestation verification. -> **For most projects, this is sufficient** โ€” a fork contributor already gets the red -> check, the per-finding annotations on their diff and the full report in the job -> summary. If you want feedback on the pull request itself, the -> [Commit Check GitHub App](https://github.com/apps/commit-check) posts a check -> run per commit with no workflow file (free on public repositories), or you can run -> this action on `pull_request_target`. Both are covered in -> **[Fork pull requests](docs/fork-pr-comments.md)**. +
-## Badging Your Repository +
+Fork and Dependabot pull requests -You can add a badge to your repository to show your contributors/users that you use commit-check! +A pull request from a fork gets a read-only `GITHUB_TOKEN`, so `pr-comments` +cannot post there. The action skips the comment with a `::warning::` and +notes it in the job summary; the check, the annotations and the summary still +work. For feedback on the pull request itself, use the +[Commit Check GitHub App](https://github.com/apps/commit-check) (free on public +repositories) or run the action on `pull_request_target` โ€” both are covered in +[Fork pull requests](docs/fork-pr-comments.md). -[![Commit Check](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml) +Dependabot pull requests are not forks, but their `pull_request` runs also get +a read-only token by default. The `pull-requests: write` grant in the +[usage example](#usage) is honoured for them; without it the action logs a +`::warning::` on the 403 and leaves the report in the job summary. Adding +`dependabot[bot]` to `ignore_authors` skips those pull requests altogether. -Markdown +
-``` -[![Commit Check](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg)](https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml) -``` +## Show that you use it -reStructuredText +[![commit-check](https://img.shields.io/badge/commit--check-enabled-2c9ccd?labelColor=0b1620&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI%2bPHBhdGggZD0iTTIxIDM0TDMwIDQzTDQ3IDIyIiBmaWxsPSJub25lIiBzdHJva2U9IiMyQzlDQ0QiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8%2bPGNpcmNsZSBjeD0iMjEiIGN5PSIzNCIgcj0iNyIgZmlsbD0iIzBCMTYyMCIgc3Ryb2tlPSIjMkM5Q0NEIiBzdHJva2Utd2lkdGg9IjUiLz48L3N2Zz4K)](https://commit-check.com) +```text +[![commit-check](https://img.shields.io/badge/commit--check-enabled-2c9ccd?labelColor=0b1620&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI%2bPHBhdGggZD0iTTIxIDM0TDMwIDQzTDQ3IDIyIiBmaWxsPSJub25lIiBzdHJva2U9IiMyQzlDQ0QiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8%2bPGNpcmNsZSBjeD0iMjEiIGN5PSIzNCIgcj0iNyIgZmlsbD0iIzBCMTYyMCIgc3Ryb2tlPSIjMkM5Q0NEIiBzdHJva2Utd2lkdGg9IjUiLz48L3N2Zz4K)](https://commit-check.com) ``` -.. image:: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml/badge.svg - :target: https://github.com/commit-check/commit-check-action/actions/workflows/commit-check.yml - :alt: Commit Check -``` - - -## Versioning -Versioning follows [Semantic Versioning](https://semver.org/). +## Versioning and feedback -## Have questions or feedback? +`@v2` follows the latest v2 release; pin a full version or a commit SHA if you +prefer. Releases follow [Semantic Versioning](https://semver.org/). Upgrading +from v1? See the [v2.0.0 release notes](https://github.com/commit-check/commit-check-action/releases/tag/v2.0.0). -To provide feedback (requesting a feature or reporting a bug), please post to [issues](https://github.com/commit-check/commit-check/issues) or start a [discussion](https://github.com/commit-check/commit-check/discussions). +Questions and ideas go to [Discussions](https://github.com/commit-check/commit-check/discussions), +bugs and feature requests to [Issues](https://github.com/commit-check/commit-check/issues).