The Commit Validator ensures that commit messages in a pull request follow specified patterns or formats, helping maintain a consistent commit history in your repository.

​
Configuration

​
type
string
required

Must be set to "commit"

​
match
string | string[]

Regex pattern(s) that commit messages should match

​
ignore
string | string[]

Regex pattern(s) for commit messages to ignore

​
ignore_merge_commits
boolean

Skip validation for merge commits (starting with “Merge ”)

​
first_only
boolean

Only validate the first commit in the PR

​
last_only
boolean

Only validate the last commit in the PR

​
message
string

Custom message to display when validation fails

​
Basic Usage

validate:
  - type: "commit"
    match: "^(feat|fix|docs): .+"
    ignore_merge_commits: true

​
Examples

​
Conventional Commits Format

Validate that commit messages follow the Conventional Commits format:

validate:
  - type: "commit"
    match: "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(\\w+\\))?: .+"
    ignore_merge_commits: true
    message: "Commit messages must follow conventional commit format: type(scope): description"

​
Issue Reference Required

Ensure commits reference an issue number:

validate:
  - type: "commit"
    match: ".*\\(#\\d+\\)$"
    message: "Commit messages must reference an issue number at the end, e.g., 'Fix login bug (#123)'"

​
Validate Only the Last Commit

For squash-and-merge workflows, you might only care about the last commit:

validate:
  - type: "commit"
    match: "^(feat|fix|docs): .+"
    last_only: true
    message: "The last commit message must follow the required format"

​
Ignore Certain Commit Patterns

Skip validation for certain types of commits:

validate:
  - type: "commit"
    match: "^[A-Z].*"
    ignore: "^(Merge |Revert |Automated )"
    ignore_merge_commits: true
    message: "Commit messages must start with a capital letter"

​
Pattern Matching

The Commit Validator uses JavaScript regular expressions for pattern matching. When specifying patterns, remember:

  • Patterns are case-sensitive by default
  • Some characters need to be escaped with a backslash (\)
  • In YAML, backslashes need to be double escaped (\\)

For case-insensitive matching, use the i flag: "/pattern/i"

​
How It Works

1

Retrieve Commits

The validator fetches all commits in the PR from the GitHub API

2

Filter Commits

Applies filtering based on ignore_merge_commits, first_only, or last_only settings

3

Check Patterns

For each commit, checks if the message matches required patterns and doesn’t match ignored patterns

4

Return Result

Returns a validation result with status (pass, fail, or error) and a message listing any non-conforming commits

​
Complete Rule Example

ruleset:
  - name: "Conventional Commits"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    validate:
      - type: "commit"
        match: "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(\\w+\\))?: .+"
        ignore_merge_commits: true
        message: "Commit messages must follow the conventional commit format"
    on_success:
      - label:
          add: ["conventional-commits"]
    on_failure:
      - comment:
          body: |
            Please ensure all your commit messages follow the conventional commit format:

            ```
            <type>(<optional scope>): <description>

            [optional body]

            [optional footer(s)]
            ```

            Where `type` is one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

            Example: `feat(auth): implement login functionality`

            The following commits don't follow this format:
            {{ validation_summary }}

​
Best Practices

Enable ignore_merge_commits to avoid validation errors on automated merge commits
Provide helpful error messages explaining the expected format
Consider combining with the title validator for a consistent history
For squash-and-merge workflows, use last_only: true

Complex validation rules may be frustrating for contributors; consider providing commit message templates