Commit-Check GitHub Action

A GitHub Action for checking commit message formatting, branch naming, committer name, email, commit signoff, and more.

What's New in v2

Important

This v2 release introduces several 🚨breaking changes. Please review the Breaking Changes section carefully before upgrading.

Breaking Changes

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 to v2.0.0.

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/commit-check.yml

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:
          # Required. With the default fetch-depth: 1 the clone holds only GitHub's
          # merge commit: the PR's own commits cannot be listed, author checks are
          # skipped, and the action warns and falls back to checking HEAD alone.
          fetch-depth: 0
      - uses: commit-check/commit-check-action@v2
        with:
          message: true
          branch: true
          author-name: false
          author-email: false
          job-summary: true
          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 <sha> into <sha> passes the default rules — so a shallow clone makes every PR look green. Author checks are skipped (⊘) for the same reason. On pull_request_target, also check out refs/pull/<number>/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	Commit Check GitHub App
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 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 discovery-unicamp Texas Instruments OpenCADC Extrawest Chainlift Mila RLinf Collective cpp-linter and many more.

Optional Inputs

`message`

Description: check git commit message following Conventional Commits.
Default: true

`branch`

Description: check git branch name following Conventional Branch.
Default: true

`author-name`

Description: check committer author name.
Default: false

`author-email`

Description: check committer author email.
Default: false

`dry-run`

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.

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 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.

`pr-title`

Description: check pull request title following Conventional Commits.
Default: false

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:

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

Without edited, only the initial title (at PR creation) is validated.

Advanced Configuration

The 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:

Via Environment Variables

Set any CCHK_* environment variable in your workflow step — no config file required:

- 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"

All available environment variables follow the naming convention: CCHK_ + uppercase option name with underscores instead of hyphens. See the full mapping in the commit-check documentation.

Via Configuration File

Add a commit-check.toml or cchk.toml to the root of your repository. Refer to the configuration guide for all available options.

Note

Configuration priority: CLI args > environment variables > config file > defaults. The action itself doesn't set any CLI flags beyond those in Optional Inputs, so env vars and config files are the recommended way to customize.

The config's top-level warn reports a rule without failing the run — see Warning Job Summary for what that looks like:

warn = ["branch", "CC003"]

Outputs

`result`

Structured check results as JSON, available to downstream steps via fromJSON:

- uses: commit-check/commit-check-action@v2
  id: commit-check
  with:
    dry-run: true # (1)

- name: Inspect results
  run: |
    echo "Status: ${{ fromJSON(steps.commit-check.outputs.result).status }}"
    echo "Scopes: ${{ toJSON(fromJSON(steps.commit-check.outputs.result).scopes) }}"

Without dry-run, a failing check ends the job before any later step runs. Use dry-run (or continue-on-error) when a downstream step is meant to read the result and decide for itself.

The top-level status is one of:

`status`	Meaning	Exit code
`pass`	every check passed	0
`warn`	nothing failed, but a rule listed under the config's `warn` found something	0
`skip`	every check declined to run (for example the author is in `ignore_authors`)	0
`fail`	at least one check failed	1 (0 with `dry-run`)

Only fail is ever non-zero; warn exists so a downstream step can react to a bent-but-not-broken policy without the run turning red:

- if: fromJSON(steps.commit-check.outputs.result).status == 'warn'
  run: echo "passed with warnings"

Each entry in scopes has a label (PR title, Commit 2/3, Branch, ...), a status like the ones above, a sha (the full hash of the commit a Commit N/M or Commit message scope checked; empty for the others) and the 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
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

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)	`bad msg`	CC001 message
Branch	`Feature/Add-Login`	CC201 branch

Show all 4 checks

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 <type>(<scope>): <description>
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

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:

::error title=CC001 message::Commit 2/2 (5584f46): The commit message should follow Conventional Commits.%0Avalue: bad msg%0ASuggest: Use <type>(<scope>): <description>
::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

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
Commit message
  ⊘ PR title (skipped)
  ⊘ Commit 1/1 (skipped)
Branch
  ⊘ Branch (skipped)
commit-check <version> · Rules reference

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 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
Show all 4 checks
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 <type>/<description> with allowed types
commit-check <version> · Rules reference

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 output reports the run as "status": "warn", with exit code 0.

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 Pull Request Comments

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 and Failure Job Summary above for what it looks like.

What differs is the lifecycle rather than the content:

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.

Fork PR Comments

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.

By default, commit-check-action handles this gracefully:

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

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 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.

Badging Your Repository

You can add a badge to your repository to show your contributors/users that you use commit-check!

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)

reStructuredText

.. 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.

Have questions or feedback?

To provide feedback (requesting a feature or reporting a bug), please post to issues or start a discussion.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
docs		docs
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
commit-check.toml		commit-check.toml
main.py		main.py
main_test.py		main_test.py
requirements.txt		requirements.txt

Uh oh!

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Commit-Check GitHub Action

What's New in v2

Breaking Changes

Table of Contents

Usage

Runner requirements

Action, pre-commit hook, or GitHub App — which to use?

Used By

Optional Inputs

message

branch

author-name

author-email

dry-run

job-summary

pr-comments

pr-title

Advanced Configuration

Via Environment Variables

Via Configuration File

Outputs

result

GitHub Action Job Summary

Success Job Summary

Failure Job Summary

Skipped Job Summary

Warning Job Summary

GitHub Pull Request Comments

Fork PR Comments

Badging Your Repository

Versioning

Have questions or feedback?

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Used by

Contributors

Languages

`message`

`branch`

`author-name`

`author-email`

`dry-run`

`job-summary`

`pr-comments`

`pr-title`

`result`