Skip to content
Commit Check
On this page

Configuration

Commit Check reads its settings from four places. When the same option is set in more than one, the first one listed wins:

  1. Command-line arguments — --subject-imperative=true
  2. Environment variables — CCHK_SUBJECT_IMPERATIVE=true
  3. A configuration file — cchk.toml or commit-check.toml
  4. Built-in defaults

The file carries the policy the project agreed on, the environment overrides it for a single CI job, and a flag overrides both for a single run.

Defaults are not "nothing"

Two different things decide whether a rule fires: whether you asked for that check at all, and what the option defaults to. A check only runs when its flag is passed — --message never evaluates branch rules — but once a check is running, these apply with no configuration file present:

Check Enforced by default
--message Conventional Commits (CC001), subject lengths of 5–80 characters (CC004, CC005), and an allow-list of ten commit types
--branch Conventional Branch (CC201) and an allow-list of twenty-one branch types
--author-name / --author-email The built-in name and email patterns (CC101, CC102)
--tag SemVer tag names, with an optional leading v (CC401)

Off until you turn them on: subject capitalization, imperative mood, required body and signoff, and rebase requirements.

The allow_* options are a mix, so read them individually rather than assuming: allow_commit_types and allow_branch_types are allow-lists that restrict from the start, while allow_merge_commits, allow_revert_commits, allow_empty_commits, allow_fixup_commits, allow_wip_commits and allow_force_push all default to permitting everything. The Default column in the rules reference is the full picture.

Where the config file lives

The file is TOML, and may be called cchk.toml or commit-check.toml. Commit Check searches four locations and uses the first that exists:

  1. cchk.toml
  2. commit-check.toml
  3. .github/cchk.toml
  4. .github/commit-check.toml

Run from a subdirectory of a repository, where none of the four is in the current directory, it looks in the same four places at the top of the repository's work tree. The current directory still comes first, so a package in a monorepo can keep a config of its own.

Pass --config to point at one directly and skip the search:

$ commit-check --config path/to/cchk.toml --message

Why .github/

Putting the file in .github/ keeps the repository root uncluttered and matches where Dependabot and Renovate already keep theirs. Commit Check treats both locations identically.

Editor autocompletion

The TOML schema is published on SchemaStore, so VS Code (via Even Better TOML), PyCharm and IntelliJ offer completion, validation and inline documentation for cchk.toml with nothing to configure.

Settings nothing reads

A key that no check reads, usually a misspelling, leaves its rule at the default. Commit Check names each one on stderr, with the closest real name:

cchk.toml
[commit]
subject_max_lenght = 50
$ echo "feat: add streaming support" | commit-check -m
⚠ unknown setting [commit] subject_max_lenght is ignored; did you mean subject_max_length?

It is a warning, not an error: the exit code and the JSON on stdout do not change. The top-level warn list and the [jira] and [pull_request] sections are not checked for unknown settings. The Python API reads no file at all (it takes a config dict), and the MCP server loads the file itself without reporting unknown settings.

Inheriting a shared config

An organization can keep one base policy and have every repository build on it. Point inherit_from at the shared file; the parent loads first, and anything set locally overrides it. The key itself is never passed to the validation engine.

.github/cchk.toml
inherit_from = "github:my-org/.github:cchk.toml"

[commit]
subject_max_length = 72  # overrides whatever the parent set

The value can be a GitHub shorthand, a local path or an HTTPS URL:

Form Example
GitHub, default branch github:owner/repo:path/to/cchk.toml
GitHub, pinned branch github:owner/repo@main:path/to/cchk.toml
Local file ../../shared/org-cchk.toml
HTTPS URL https://example.com/shared/cchk.toml

Inheritance fails open

If the target is unreachable or the format is not recognized, Commit Check ignores the inheritance and uses the local configuration alone, printing a one-line ⊘ inherit_from ... could not be loaded notice on stderr; the exit code does not change. Plain HTTP URLs are rejected the same way. Only one level is followed: an inherit_from inside the parent is ignored, with a notice. A repository that stops inheriting still passes its own checks, so pin the branch when the policy matters.

Pull requests: every commit, or the squash message

By default the GitHub App checks every commit of a pull request on its own. A team that squash-merges does not keep those commits: what lands on the base branch is one commit whose message GitHub builds from the pull request. Checking the drafts instead of the result is the reason teams turn commit rules off, so the App can check the result:

cchk.toml
[pull_request]
check = "squash"

With check = "squash" a pull request gets one Commit Check result on its head commit, and it is the message a squash merge would produce, built the way GitHub builds it from the repository's merge settings (Settings → General → Pull Requests):

Repository setting Title checked Body checked
Default to pull request title The pull request title The pull request description, the commit messages, or nothing, per the setting
Default message, one commit That commit's title That commit's body
Default message, several commits The pull request title The commit messages, one per bullet

The pull request number GitHub appends to the title (… (#42)) is part of what is checked, so a subject-length rule sees the real subject. Editing the title or description re-runs the check; pushes to the branch are not checked commit by commit. Author checks run on the head commit, the branch check on the head branch.

check = "commits" is the default and the behaviour of the CLI, the pre-commit hook and the Action, which have no pull request to read. The setting is read by the App only.

Report a rule without enforcing it

A rule is normally on or off. warn gives it a third setting: run, report the finding in full, and never fail the run. It is a top-level key, so it goes before the first section, and it names a check or its rule ID in any case:

cchk.toml
warn = ["branch", "CC003"]

[commit]
subject_imperative = true

[branch]
conventional_branch = true

A warned rule prints the same block as a failure with warning in place of failed, no rejection header, and one closing line saying the run is not failed by it; with --compact it is one [WARN] line. A one-line notice on stderr names the warned rules, so a hook that exits 0 after red-looking output is not mistaken for a broken hook. The exit code counts only enforced rules. In --format json the check's status is warn, the top-level status stays pass unless an enforced rule failed, and warnings counts them — see Reading the JSON.

A name that matches no rule is a configuration error that lists the known rules, so a typo cannot leave a rule silently enforced. Rules not listed behave as before.

This is how a team adopts a rule gradually: turn it on as a warning, watch what it catches for a week, then drop it from warn once the history is clean. It is also how a shared config carries both kinds of rule at once — the ones every repository must satisfy, and the ones it is asking teams to move towards. A repository's own warn list replaces the shared one, as any inherited key does.

A worked example

Every line below that differs from the built-in default is marked, so it is clear what this file changes:

cchk.toml
# changed: report the branch rule without enforcing it (nothing is warned by default)
warn = ["branch"]

[commit]
# https://www.conventionalcommits.org
conventional_commits = true
# message_pattern = ""             # optional: a custom regex, replacing the above
subject_capitalized = false
subject_imperative = true          # changed: off by default
subject_max_length = 80
subject_min_length = 5
# changed: a subset of the default list, which also has perf, build and ci
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
allow_merge_commits = true
allow_revert_commits = true
allow_empty_commits = false        # changed: allowed by default
allow_fixup_commits = true
allow_wip_commits = false          # changed: allowed by default
require_body = false
require_signed_off_by = false
ai_attribution = "disclose"        # changed: "ignore" by default; see the AI policy guide
# ignore_authors = []              # optional: bypass all commit checks for these authors

[push]
allow_force_push = true            # set false to block force pushes

[branch]
# https://conventionalbranch.org
conventional_branch = true
# changed: the spec's five purpose types only. The default is a superset —
# these plus their aliases feat and fix, AI agent prefixes, the other
# Conventional Commit types and bot prefixes — so setting this at all narrows
# it. Omit the line to accept all of them.
allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore"]
# true also holds the part after "/" to the spec's grammar
require_description_grammar = false
# allow_branch_names = []          # optional: extra standalone names, e.g. ["staging"]
# require_rebase_target = "main"   # optional: no rebase requirement by default
# ignore_authors = []              # optional: as above, for branch checks

allow_* options describe what is permitted

They read backwards from most linters. allow_wip_commits = false is the setting that rejects WIP commits; leaving it at its default of true lets them through.

Command-line arguments

Every option can be set as a flag, which is what makes a TOML file optional entirely — useful when the policy lives in .pre-commit-config.yaml instead.

Type Form
Boolean --option-name=true / --option-name=false
Integer --option-name=80
List --option-name=value1,value2,value3
String --option-name=value
$ commit-check --message --subject-imperative=false
$ commit-check --message --subject-max-length=72
$ commit-check --message --allow-commit-types=feat,fix,docs
$ commit-check --branch --allow-branch-types=feature,bugfix,hotfix

Used from a hook definition, with no config file anywhere in the repository:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.23.0
    hooks:
      - id: check-message
        args:
          - --subject-imperative=false
          - --subject-max-length=100
          - --allow-merge-commits=false

Environment variables

Any option can also be set through the environment, which is the practical way to vary policy per CI job without editing the file. Uppercase the option name, replace hyphens with underscores, and prefix CCHK_:

$ export CCHK_SUBJECT_MAX_LENGTH=72
$ export CCHK_ALLOW_COMMIT_TYPES=feat,fix,docs,chore
$ CCHK_SUBJECT_MAX_LENGTH=100 commit-check --message

The full mapping between the three forms:

TOML Config Environment Variable CLI Argument
conventional_commits = true CCHK_CONVENTIONAL_COMMITS=true --conventional-commits=true
message_pattern = "^PROJ-\\d+: .+" CCHK_MESSAGE_PATTERN=^PROJ-\\d+: .+ N/A (config file only)
subject_capitalized = false CCHK_SUBJECT_CAPITALIZED=false --subject-capitalized=false
subject_imperative = true CCHK_SUBJECT_IMPERATIVE=true --subject-imperative=true
subject_max_length = 80 CCHK_SUBJECT_MAX_LENGTH=80 --subject-max-length=80
subject_min_length = 5 CCHK_SUBJECT_MIN_LENGTH=5 --subject-min-length=5
allow_commit_types = ["feat", "fix"] CCHK_ALLOW_COMMIT_TYPES=feat,fix --allow-commit-types=feat,fix
allow_merge_commits = true CCHK_ALLOW_MERGE_COMMITS=true --allow-merge-commits=true
allow_revert_commits = true CCHK_ALLOW_REVERT_COMMITS=true --allow-revert-commits=true
allow_empty_commits = false CCHK_ALLOW_EMPTY_COMMITS=false --allow-empty-commits=false
allow_fixup_commits = true CCHK_ALLOW_FIXUP_COMMITS=true --allow-fixup-commits=true
allow_wip_commits = false CCHK_ALLOW_WIP_COMMITS=false --allow-wip-commits=false
require_body = false CCHK_REQUIRE_BODY=false --require-body=false
require_signed_off_by = false CCHK_REQUIRE_SIGNED_OFF_BY=false --require-signed-off-by=false
ignore_authors = ["bot"] CCHK_IGNORE_AUTHORS=bot,user --ignore-authors=bot,user
author_email_pattern = '^.+@example\.com$' CCHK_AUTHOR_EMAIL_PATTERN=^.+@example\.com$ --author-email-pattern=^.+@example\.com$
author_name_pattern = '^.+ .+$' CCHK_AUTHOR_NAME_PATTERN=^.+ .+$ --author-name-pattern=^.+ .+$
conventional_branch = true CCHK_CONVENTIONAL_BRANCH=true --conventional-branch=true
allow_branch_types = ["feature"] CCHK_ALLOW_BRANCH_TYPES=feature,bugfix --allow-branch-types=feature,bugfix
allow_branch_names = ["staging", "production"] CCHK_ALLOW_BRANCH_NAMES=staging,production --allow-branch-names=staging,production
require_description_grammar = true CCHK_REQUIRE_DESCRIPTION_GRAMMAR=true --require-description-grammar=true
require_rebase_target = "main" CCHK_REQUIRE_REBASE_TARGET=main --require-rebase-target=main
allow_force_push = true CCHK_ALLOW_FORCE_PUSH=true --no-force-push (sets allow_force_push to false)
ai_attribution = "forbid" CCHK_AI_ATTRIBUTION=forbid --ai-attribution=forbid
ai_disclosure_trailers = ["Assisted-by"] CCHK_AI_DISCLOSURE_TRAILERS=Assisted-by --ai-disclosure-trailers=Assisted-by
ai_disclosure_pattern = '^\S+/\S+$' CCHK_AI_DISCLOSURE_PATTERN=^\S+/\S+$ --ai-disclosure-pattern='^\S+/\S+$'
ignore_authors = ["bot"] (in branch section) CCHK_BRANCH_IGNORE_AUTHORS=bot,user --branch-ignore-authors=bot,user
regex = "^v\\d+\\.\\d+\\.\\d+$" (in tag section) CCHK_TAG_REGEX=^v\\d+\\.\\d+\\.\\d+$ --tag-regex=^v\\d+\\.\\d+\\.\\d+$
max_size = "5MB" (in files section) CCHK_FILES_MAX_SIZE=5MB --files-max-size=5MB
prohibited_patterns = ["*.pem"] (in files section) CCHK_FILES_PROHIBITED_PATTERNS=*.pem,.env --files-prohibited-patterns=*.pem,.env
max_path_length = 250 (in files section) CCHK_FILES_MAX_PATH_LENGTH=250 --files-max-path-length=250

Which value wins

The four sources layer, so the same option can be set in several at once. Only the highest-priority one takes effect:

$ grep subject_max_length cchk.toml
subject_max_length = 100

$ export CCHK_SUBJECT_MAX_LENGTH=80

$ commit-check --message --subject-max-length=50

The limit applied is 50 — the flag beats the environment, which beats the file. Nothing warns about the values that lost, which is worth remembering when a setting in the file appears to have no effect.

Every option

Types are as TOML understands them. A pattern, a subject length, or a type or name list given a value of another type stops the run with exit 2 and names the setting:

cchk.toml
[commit]
subject_max_length = "50"
$ echo "feat: add streaming support" | commit-check -m
Error: [commit] subject_max_length must be a whole number, got '50'

allow_commit_types, allow_branch_types and allow_branch_names also take one comma-separated string, as --allow-commit-types does. A boolean has to be a TOML boolean: "false" in quotes is a non-empty string, and it counts as true.

A default shown as "" means the option is unset, which is never the same as the check being off — but it does not mean the same thing twice, so read the description rather than the default:

  • message_pattern unset leaves conventional_commits to generate the pattern. CC001 still runs.
  • author_name_pattern unset falls back to the built-in name pattern. CC101 still runs.
  • require_rebase_target unset is the one case where the check really does not run — there is no branch to compare against.

Top level

These two sit above every section, at the top of the file.

inherit_fromstrDefault "" (none)
A shared config to start from: a path, a URL, or github:owner/repo:path. This file's own settings override it. See Inheriting a shared config and Across an organization.
warnlist[str]Default [] (nothing warned)
Checks or rule IDs to report without failing, e.g. ["branch", "CC003"]. See Report a rule without enforcing it.

[commit]

conventional_commitsboolDefault true
Enforce Conventional Commits specification.
message_patternstrDefault "" (no custom pattern)
Custom regex pattern for commit message validation. When set, this pattern replaces the auto-generated Conventional Commits regex entirely, making it possible to enforce custom formats such as JIRA smart commits (e.g., "^PROJ-\\d+: .+"). When message_pattern is set (non-empty) it takes precedence over conventional_commits.
subject_capitalizedboolDefault false
Subject must start with a capital letter.
subject_imperativeboolDefault false
Subject must be in imperative mood. Judged on the first word's form, so a verb no list contains is still accepted — see CC003.
subject_max_lengthintDefault 80
Maximum length of the subject line, not counting the (#123) a GitHub squash merge adds. Commits by dependabot[bot] and renovate[bot] skip it. 0 turns the check off.
subject_min_lengthintDefault 5
Minimum length of the subject line, not counting the (#123) a GitHub squash merge adds. Commits by dependabot[bot] and renovate[bot] skip it. 0 turns the check off.
allow_commit_typeslist[str]Default ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci"]
Allowed commit types when conventional_commits is true.
allow_merge_commitsboolDefault true
Allow merge commits.
allow_revert_commitsboolDefault true
Allow revert commits.
allow_empty_commitsboolDefault true
Allow empty commits.
allow_fixup_commitsboolDefault true
Allow fixup commits: fixup!, squash! and amend! subjects.
allow_wip_commitsboolDefault true
Allow work-in-progress commits (e.g., "WIP: ").
require_bodyboolDefault false
Require a body in the commit message.
ignore_authorslist[str]Default [] (none ignored)
List of commit authors or co-authors (Co-authored-by: lines) to bypass all commit checks. Useful for bots (e.g., "dependabot[bot]", "coderabbitai[bot]").
author_email_patternstrDefault ^.+@.+$
Custom regex for the author email check. When empty, the built-in default pattern is used. This option only takes effect when the author_email check is enabled (-e / --author-email).
author_name_patternstrDefault "" (built-in default)
Custom regex for the author name check. When empty, the built-in default pattern is used (it is not disabled). This option only takes effect when the author_name check is enabled (-n / --author-name).
require_signed_off_byboolDefault false
Require "Signed-off-by" line in the commit message footer.
ai_attributionstrDefault "ignore"
AI attribution policy. "forbid" rejects any commit carrying AI attribution — a co-author or sign-off line naming a known tool, a disclosure trailer, a vendor mark (CC013). "disclose" accepts AI assistance that is disclosed with one of ai_disclosure_trailers (CC014) and rejects the tool as a co-author (CC015) or as a sign-off (CC016). "ignore" disables the check. Any other value is a configuration error.
ai_disclosure_trailerslist[str]Default ["Assisted-by", "Generated-by"]
The trailers that disclose AI assistance under "disclose". The first one is what a correction is written with. Listing Co-authored-by says the project accepts the tool as a co-author, and CC015 then passes. Signed-off-by is refused: only a person can certify the DCO.
ai_disclosure_patternstrDefault "" (any value)
A regex the disclosure trailer's value must match under "disclose", e.g. '^\S+/\S+$' for an agent/model format. Empty accepts any value, but a trailer with no value at all is reported whatever the pattern is.

The GitHub App also reads require_verified (bool, default false) in this section: every commit has to show Verified on GitHub. The CLI and the Action do not check signatures; see Verified commits.

[branch]

conventional_branchboolDefault true
Enforce Conventional Branch specification.
allow_branch_typeslist[str]Default ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "style", "test", "ai", "claude", "codex", "copilot", "cursor", "agents", "dependabot", "renovate"]
Allowed branch types when conventional_branch is true. The default is a superset of the Conventional Branch spec: the spec's types (feature, bugfix, hotfix, release, chore, their aliases feat and fix, and the AI agent prefixes ai, claude, codex, copilot, cursor) plus the other Conventional Commit types (build, ci, docs, perf, refactor, style, test), agents (the prefix VS Code's Agents window uses) and bot prefixes (dependabot, renovate). For strict spec-only validation, set this option explicitly to the spec's types; CC201 has the full config.
require_description_grammarboolDefault false
Also hold the description after <type>/ to the Conventional Branch grammar: lowercase letters and digits, words joined by single hyphens, dots only inside a word. Off by default, because bot branches such as dependabot/npm_and_yarn/lodash-4.17.21 do not follow it. See CC201.
allow_branch_nameslist[str]Default [] (empty list)
Additional standalone branch names allowed when conventional_branch is true (e.g., ["staging", "production"]). By default, main, master, develop, HEAD, PR-* and gh-readonly-queue/* (GitHub merge queue branches) are always allowed.
require_rebase_targetstrDefault "" (no requirement)
Target branch for rebase requirement. If not set, no rebase validation is performed.
ignore_authorslist[str]Default [] (none ignored)
List of authors to ignore (i.e., always allow).

[push]

allow_force_pushboolDefault true
Allow force pushes. Set to false to block force pushes when used as a pre-push hook or with --no-force-push.

[tag]

regexstrDefault ^v?(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$
Pattern a tag name must match. The default is the official SemVer pattern with an optional leading v, so both v1.2.3 and 1.2.3 pass. An empty value disables the pattern match.

[files]

max_sizestrDefault "" (disabled)
Largest a committed file may be, in bytes or with a KB/MB/GB suffix (binary units, so 5MB is 5 × 1024²). Empty disables the rule.
prohibited_patternslist[str]Default [] (empty list)
fnmatch patterns a committed path may not match, e.g. ["*.pem", ".env", "id_rsa*"]. A bare pattern also matches the file name at any depth. Matching is case-sensitive on every platform, like git pathspecs. Empty disables the rule.
max_path_lengthintDefault 0 (disabled)
Longest a committed file path may be, in characters. 0 disables the rule.

[pull_request]

checkstrDefault "commits"
GitHub App only. "commits" checks every commit of a pull request on its own; "squash" checks the one message a squash merge would land, built from the repository's merge settings. See Pull requests.
ai_declaration_checkboxeslist[str]Default [] (rule off)
The texts of the AI declaration boxes in the pull request template, one per box. When set, a pull request description checked with --ai-attribution-only must tick exactly one of them; see CC501. Read by the CLI, the Action and the App.
body_ai_attributionboolDefault false
GitHub App only. Check the pull request description against the AI rules (CC013 to CC016), and its AI declaration boxes when ai_declaration_checkboxes is set. The Action's pr-body-ai-attribution input does the same. See AI-written pull requests.
ai_labelbool or strDefault false
GitHub App only. Label a pull request an AI tool wrote any of: true for ai-assisted, or the label's name. Labels are only added, never removed.

[jira]

GitHub App only; the CLI and the Action ignore the section. See Jira ticket references.

requiredboolDefault false
Every commit message, or the squash message, has to reference a Jira ticket.
patternstrDefault [A-Z]+-\d+
Regex for a ticket reference, e.g. "PROJ-\\d+" in TOML for one project.
suggestionstrDefault "" (built-in text)
The fix shown when the reference is missing.
Esc
↵ to open ↑↓ to move Esc to close
Keyboard shortcuts
Ctrl K /
Open search and commands
t
Toggle dark mode
[ ]
Previous / next page
j k
Previous / next heading
?
Show this help