From 7779aa97eeeaa42d7fa07e3115cf053bb9c9df9b Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 16:50:23 +0000 Subject: [PATCH 1/5] docs: open the README with one-check workflows for PR titles and branch names Most of the field does one thing: the most-used PR title check only reads the title, and branch name checks only read the branch. Show that the Action does each in a complete workflow before the full setup, so a reader who wants one check finds it without reading the inputs table first. --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/README.md b/README.md index ae90ba8..215fb34 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,54 @@ request — message, branch, author, and optionally the PR title — against you `cchk.toml`, and reports the result in the job summary, as annotations on the diff and, if you want, as a PR comment. +## Start with one check + +Each of these is a complete workflow. Pick one, then turn on more checks when +you need them. + +**Pull request title only.** On a repository that squash-merges, the title +becomes the commit on `main`, so it is the one message worth checking: + +```yaml +name: PR Title + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +jobs: + pr-title: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: commit-check/commit-check-action@v2 + with: + message: false + branch: false + pr-title: true +``` + +**Branch name only**, against [Conventional Branch](https://conventionalbranch.org/): + +```yaml +name: Branch Name + +on: + pull_request: + +jobs: + branch-name: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: commit-check/commit-check-action@v2 + with: + message: false +``` + +Both read the repository's `cchk.toml` if there is one, so a custom type list +or an extra allowed branch name works without changing the workflow. + ## Usage Add a workflow, e.g. `.github/workflows/commit-check.yml`: From 16d36b7e144f750c03b86347d3808610226e6075 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 16:57:18 +0000 Subject: [PATCH 2/5] docs: note that a single-commit squash lands the commit message by default GitHub's default squash message uses the pull request title only when the pull request has more than one commit. Say so next to the PR-title-only workflow, with the setting that makes the title the message that lands. --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 215fb34..123be77 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,10 @@ Each of these is a complete workflow. Pick one, then turn on more checks when you need them. **Pull request title only.** On a repository that squash-merges, the title -becomes the commit on `main`, so it is the one message worth checking: +becomes the commit on `main`, so it is the one message worth checking. With +GitHub's default squash message, a pull request of a single commit lands that +commit's message instead; set the squash commit message to "Pull request +title" in the repository settings to make the title the one that lands: ```yaml name: PR Title From 8ccc4784b7a1ed323dd9236ac81b54922a2c0086 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 17:38:28 +0000 Subject: [PATCH 3/5] docs: drop inputs that repeat their defaults from the full workflow message and branch are on by default and author-name, author-email are off; job-summary is on. Spelling them out made the example look like five settings a user has to write. Keep pr-comments, the one it changes. --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 123be77..fff595c 100644 --- a/README.md +++ b/README.md @@ -103,11 +103,8 @@ jobs: fetch-depth: 0 - uses: commit-check/commit-check-action@v2 with: - message: true - branch: true - author-name: false - author-email: false - job-summary: true + # Commit messages and the branch name are checked by default; + # see Inputs for the rest. pr-comments: true ``` From 2af8e4ec1f1bb7df0010df2dc29e01c42432c430 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 17:45:11 +0000 Subject: [PATCH 4/5] docs: open the README with three examples: commits and branch, PR title, job summary --- README.md | 189 +++++++++++++++++++++++++----------------------------- 1 file changed, 89 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index fff595c..2a36fec 100644 --- a/README.md +++ b/README.md @@ -27,97 +27,137 @@ request — message, branch, author, and optionally the PR title — against you `cchk.toml`, and reports the result in the job summary, as annotations on the diff and, if you want, as a PR comment. -## Start with one check +## Usage + +Three examples. Each is a complete workflow, e.g. +`.github/workflows/commit-check.yml`; start with the one you need. -Each of these is a complete workflow. Pick one, then turn on more checks when -you need them. +### 1. Commit messages and branch name -**Pull request title only.** On a repository that squash-merges, the title -becomes the commit on `main`, so it is the one message worth checking. With -GitHub's default squash message, a pull request of a single commit lands that -commit's message instead; set the squash commit message to "Pull request -title" in the repository settings to make the title the one that lands: +Both are checked by default, against +[Conventional Commits](https://www.conventionalcommits.org/) and +[Conventional Branch](https://conventionalbranch.org/), so the action needs no +inputs: ```yaml -name: PR Title +name: Commit Check on: pull_request: - types: [opened, edited, synchronize, reopened] jobs: - pr-title: + commit-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - - uses: commit-check/commit-check-action@v2 with: - message: false - branch: false - pr-title: true + fetch-depth: 0 # recommended: read the PR's commits from the clone + - uses: commit-check/commit-check-action@v2 ``` -**Branch name only**, against [Conventional Branch](https://conventionalbranch.org/): +> [!NOTE] +> `fetch-depth: 0` is recommended, not required. A shallow clone holds only +> GitHub's merge commit, so the action lists the pull request's commits +> through the API — up to 250, with `pull-requests: read` — and fetches the +> head commit for the author checks. If the commits cannot be listed, it warns +> and checks HEAD alone; if the head commit cannot be fetched, it warns and +> skips the author checks. + +### 2. Pull request title + +On a repository that squash-merges, the title becomes the commit on `main`, so +it is the one message worth checking. With GitHub's default squash message, a +pull request of a single commit lands that commit's message instead; set the +squash commit message to "Pull request title" in the repository settings to +make the title the one that lands: ```yaml -name: Branch Name +name: PR Title on: pull_request: + types: [opened, edited, synchronize, reopened] jobs: - branch-name: + pr-title: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: commit-check/commit-check-action@v2 with: message: false + branch: false + pr-title: true ``` -Both read the repository's `cchk.toml` if there is one, so a custom type list -or an extra allowed branch name works without changing the workflow. +### 3. Job summary -## Usage +Every run writes its report to the job summary; `job-summary` is on by +default. 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: -Add a workflow, e.g. `.github/workflows/commit-check.yml`: +> **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/)_ -```yaml -name: Commit Check +The rest follow the same layout: -on: - pull_request: - branches: 'main' +- **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 `✔`. -jobs: - commit-check: - runs-on: ubuntu-latest - permissions: # use permissions because use of pr-comments +The step log prints the same tree, plus one annotation per finding on the +Files changed tab. To post the same report on the pull request, edited in +place on later runs, add `pr-comments: true` and grant the job +`pull-requests: write`: + +```yaml + permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v7 - with: - # Recommended: the action then reads the PR's commits from the clone. - # With the default fetch-depth: 1 it asks the GitHub API instead. - fetch-depth: 0 - uses: commit-check/commit-check-action@v2 with: - # Commit messages and the branch name are checked by default; - # see Inputs for the rest. pr-comments: true ``` -> [!NOTE] -> `fetch-depth: 0` is recommended, not required. A shallow clone holds only -> GitHub's merge commit, so the action lists the pull request's commits -> through the API — up to 250, with `pull-requests: read` — and fetches the -> head commit for the author checks. If the commits cannot be listed, it warns -> and checks HEAD alone; if the head commit cannot be fetched, it warns and -> skips the author checks. - -Runs on `ubuntu-latest`, `macos-latest` and `windows-latest`. Self-hosted -runners need a few tools — see [Good to know](#good-to-know). +All three read the repository's `cchk.toml` if there is one, so a custom type +list or an extra allowed branch name works without changing the workflow. The +action runs on `ubuntu-latest`, `macos-latest` and `windows-latest`; +self-hosted runners need a few tools — see [Good to know](#good-to-know). ## Inputs @@ -156,57 +196,6 @@ 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/). -## What it looks like - -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: - -> **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 rest follow the same layout: - -- **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 ### `result` @@ -332,8 +321,8 @@ repositories) or run the action on `pull_request_target` — both are covered in 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 +[job summary example](#3-job-summary) 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. From 26b557752f2b4ef6db8fa1d6187742168ac7abab Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 18:05:39 +0000 Subject: [PATCH 5/5] docs: show only the main checks in the usage example --- README.md | 150 ++++++++++++++++++++---------------------------------- 1 file changed, 56 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 2a36fec..7d0508c 100644 --- a/README.md +++ b/README.md @@ -29,30 +29,34 @@ diff and, if you want, as a PR comment. ## Usage -Three examples. Each is a complete workflow, e.g. -`.github/workflows/commit-check.yml`; start with the one you need. - -### 1. Commit messages and branch name - -Both are checked by default, against -[Conventional Commits](https://www.conventionalcommits.org/) and -[Conventional Branch](https://conventionalbranch.org/), so the action needs no -inputs: +Add a workflow, e.g. `.github/workflows/commit-check.yml`: ```yaml name: Commit Check on: pull_request: + branches: 'main' jobs: commit-check: runs-on: ubuntu-latest + permissions: # use permissions because use of pr-comments + contents: read + pull-requests: write steps: - uses: actions/checkout@v7 with: - fetch-depth: 0 # recommended: read the PR's commits from the clone + # Recommended: the action then reads the PR's commits from the clone. + # With the default fetch-depth: 1 it asks the GitHub API instead. + fetch-depth: 0 - uses: commit-check/commit-check-action@v2 + with: + message: true + branch: true + pr-title: true + job-summary: true + pr-comments: true ``` > [!NOTE] @@ -63,39 +67,51 @@ jobs: > and checks HEAD alone; if the head commit cannot be fetched, it warns and > skips the author checks. -### 2. Pull request title +Runs on `ubuntu-latest`, `macos-latest` and `windows-latest`. Self-hosted +runners need a few tools — see [Good to know](#good-to-know). -On a repository that squash-merges, the title becomes the commit on `main`, so -it is the one message worth checking. With GitHub's default squash message, a -pull request of a single commit lands that commit's message instead; set the -squash commit message to "Pull request title" in the repository settings to -make the title the one that lands: +## Inputs -```yaml -name: PR Title +| 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 | -on: - pull_request: - types: [opened, edited, synchronize, reopened] +> [!TIP] +> `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. -jobs: - pr-title: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7 - - uses: commit-check/commit-check-action@v2 - with: - message: false - branch: false - pr-title: true +## Configuration + +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 + env: + CCHK_SUBJECT_CAPITALIZED: "true" + CCHK_REQUIRE_SIGNED_OFF_BY: "true" + CCHK_AI_ATTRIBUTION: "forbid" + CCHK_ALLOW_COMMIT_TYPES: "feat,fix,docs,chore" ``` -### 3. Job summary +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/). + +## What it looks like -Every run writes its report to the job summary; `job-summary` is on by -default. 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: +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: > **Commit Check** > @@ -139,62 +155,8 @@ The rest follow the same layout: `ignore_authors` — reads `⊘`, never `✔`. The step log prints the same tree, plus one annotation per finding on the -Files changed tab. To post the same report on the pull request, edited in -place on later runs, add `pr-comments: true` and grant the job -`pull-requests: write`: - -```yaml - permissions: - contents: read - pull-requests: write - steps: - - uses: actions/checkout@v7 - - uses: commit-check/commit-check-action@v2 - with: - pr-comments: true -``` - -All three read the repository's `cchk.toml` if there is one, so a custom type -list or an extra allowed branch name works without changing the workflow. The -action runs on `ubuntu-latest`, `macos-latest` and `windows-latest`; -self-hosted runners need a few tools — see [Good to know](#good-to-know). - -## Inputs - -| 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] -> `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. - -## Configuration - -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 - env: - CCHK_SUBJECT_CAPITALIZED: "true" - CCHK_REQUIRE_SIGNED_OFF_BY: "true" - CCHK_AI_ATTRIBUTION: "forbid" - CCHK_ALLOW_COMMIT_TYPES: "feat,fix,docs,chore" -``` - -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/). +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 @@ -321,8 +283,8 @@ repositories) or run the action on `pull_request_target` — both are covered in 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 -[job summary example](#3-job-summary) is honoured for them; without it the -action logs a `::warning::` on the 403 and leaves the report in the job summary. Adding +[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.