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.

Table of Contents

• Usage
• Optional Inputs
• GitHub Action Job Summary
• GitHub Pull Request Comments
• Advanced Configuration
• Fork PR Comments
• Badging Your Repository
• Versioning

Usage

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

name: Commit Check

on:
  push:
  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@v5
        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: ${{ github.event_name == 'pull_request' }}

Note

This action supports running on Linux, macOS, and Windows (ubuntu-latest, macos-latest, windows-latest).

Used By

Apache   discovery-unicamp   Texas Instruments   OpenCADC   Extrawest Chainlift   Mila   RLinf   Collective   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: run checks without failing. exit code is 0; otherwise is 1.
• 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. See docs/fork-pr-comments.md for details on how to enable this feature for fork contributions.

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.

GitHub Action Job Summary

By default, commit-check-action results are shown on the job summary page of the workflow.

Success Job Summary

Failure Job Summary

GitHub Pull Request Comments

Success Pull Request Comment

Failure Pull Request Comment

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

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.