The Title Validator checks if a pull request’s title meets specified requirements, such as following a pattern, having a minimum or maximum length, or containing specific text.

​
Configuration

​
type
string
required

Must be set to "title"

​
match
string | string[]

Regex pattern(s) that the title should match

​
length
object

Title length constraints

​
length.min
number

Minimum title length in characters

​
length.max
number

Maximum title length in characters

​
message
string

Custom message to display when validation fails

​
Basic Usage

validate:
  - type: "title"
    match: "^(feat|fix|docs): .+"
    message: "PR title must start with feat:, fix:, or docs:"

​
Examples

​
Conventional Commits Format

Validate that PR titles follow the Conventional Commits format:

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

​
Title Length Requirements

Ensure titles are neither too short nor too long:

validate:
  - type: "title"
    length:
      min: 10
      max: 100
    message: "PR title must be between 10 and 100 characters"

​
Multiple Patterns

Allow multiple title formats:

validate:
  - type: "title"
    match:
      - "^\\[BUG\\] .+"
      - "^\\[FEATURE\\] .+"
      - "^\\[DOCS\\] .+"
    message: "PR title must start with [BUG], [FEATURE], or [DOCS]"

​
Combined Requirements

Combine pattern matching and length requirements:

validate:
  - type: "title"
    match: "^(feat|fix|docs): .+"
    length:
      min: 10
    message: "PR title must start with type prefix and be at least 10 characters"

​
Pattern Matching

The Title 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 PR Title

The validator retrieves the PR title from the GitHub event context

2

Check Pattern

If match is specified, it checks if the title matches any of the regex patterns

3

Check Length

If length is specified, it verifies the title length is within the specified range

4

Return Result

Returns a validation result with status (pass, fail, or error) and a message

​
Complete Rule Example

ruleset:
  - name: "PR Title Convention"
    when:
      - "pull_request.opened"
      - "pull_request.edited"
    validate:
      - type: "title"
        match: "^(feat|fix|docs)(\\(\\w+\\))?: .+"
        length:
          min: 10
          max: 100
        message: "PR title must follow the format: type(scope): description"
    on_success:
      - label:
          add: ["valid-title"]
    on_failure:
      - comment:
          body: |
            Please update your PR title to follow our conventions:

            - Start with a type: `feat`, `fix`, or `docs`
            - Optionally include a scope in parentheses
            - Add a colon and a space
            - Write a description (at least 10 characters)

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

            {{ validation_summary }}

​
Best Practices

Use clear and consistent title patterns across your repositories
Provide helpful error messages explaining the expected format
Consider combining with the commit validator for consistency
Set reasonable length limits that allow for informative titles

Complex regex patterns may be difficult for contributors to understand; provide clear examples