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

• 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
• Optional Inputs
• GitHub Action Job Summary
• GitHub Pull Request Comments
• Advanced Configuration
• Fork PR Comments
• Badging Your Repository
• Versioning

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:
          fetch-depth: 0  # Required for merge-base checks
      - uses: commit-check/commit-check-action@v2
        with:
          message: true
          branch: true
          author-name: false
          author-email: false
          job-summary: true
          pr-comments: true

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

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

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

• Description: check committer author name.
• Default: false

• Description: check committer author email.
• Default: false

• Description: run checks without failing. exit code is 0; otherwise is 1.
• Default: false

• Description: display job summary to the workflow run.
• Default: true

• Description: post results to the pull request comments.
• Default: false

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

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

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:

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.

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

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

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

Each scope carries the check outcomes (rule_id, check, status, value, error, suggest, docs_url) exactly as produced by commit-check --format json, so downstream jobs can build their own reports or gate on individual rules.

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.

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 (feat: add login page)
Branch
  ✔ Branch (feature/add-login)

commit-check <version> · Rules reference

Failures open with a count, then a table of only the scopes that failed — every rule ID links to its documentation — with the full tree still one click away:

Commit Check

❌ 2 of 4 checks failed

Scope	Checked value	Failed checks
Commit 2/2	bad msg	CC001 message
Branch	my-changes	CC201 branch

Show all 4 checks

Commit message
  ✔ PR title (feat: add login page)
  ✔ Commit 1/2 (feat: add login page)
  ✖ Commit 2/2 (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: my-changes
        The branch should follow Conventional Branch.
        Suggest: Use <type>/<description> with allowed types

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.

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.

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 <!-- commit-check-action --> 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.

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 — contributors can see check results in the action Job Summary. But if you must have PR comments on fork contributions, see the Fork PR Comments documentation for two recommended approaches with ready-to-use workflow examples.

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 follows Semantic Versioning.

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