The Branch Validator ensures that the base and head branches of a pull request follow specified naming conventions. This helps maintain consistent branch names that communicate the purpose of changes and follow your team’s workflow.

​
Configuration

​
type
string
required

Must be set to "branch"

​
base
object

Validation rules for the base branch (the branch you’re merging into)

​
base.match
string | string[]

Pattern(s) that the base branch name should match

​
base.ignore
string | string[]

Pattern(s) that the base branch name should not match

​
base.message
string

Custom message for base branch validation failures

​
head
object

Validation rules for the head branch (the branch with your changes)

​
head.match
string | string[]

Pattern(s) that the head branch name should match

​
head.ignore
string | string[]

Pattern(s) that the head branch name should not match

​
head.message
string

Custom message for head branch validation failures

​
Basic Usage

validate:
  - type: "branch"
    head:
      match: "^(feature|bugfix|hotfix)/[a-z0-9-_]+"
      message: "Branch name must follow pattern: type/description (e.g., feature/add-login)"

​
Examples

​
Head Branch Naming Convention

Enforce a specific pattern for feature branches:

validate:
  - type: "branch"
    head:
      match: "^(feature|bugfix|hotfix|release)/[a-z0-9-_]+"
      message: "Branch name must start with feature/, bugfix/, hotfix/, or release/"

​
Protected Base Branches

Ensure PRs only target specific base branches:

validate:
  - type: "branch"
    base:
      match: ["main", "develop", "release-.*"]
      message: "PRs can only target main, develop, or release branches"

​
Prevent Direct Production Changes

Prevent direct PRs to production branches:

validate:
  - type: "branch"
    base:
      match: "production"
      ignore: true
      message: "Direct PRs to production are not allowed. Please target staging first."

​
Combined Rules

Validate both base and head branches:

validate:
  - type: "branch"
    base:
      match: ["main", "develop"]
      message: "PRs must target either main or develop"
    head:
      match: "^(feature|bugfix|hotfix)/[a-z0-9-_]+"
      ignore: ["wip/.*", "temp/.*"]
      message: "Feature branches must follow naming convention and not be WIP or temporary"

​
Pattern Matching

The Branch Validator supports several pattern matching methods:

  1. Exact match: "main"
  2. Glob patterns: "release-*"
  3. Regular expressions: "/^feature\/.*$/" (enclosed in forward slashes)

​
How It Works

1

Get Branch Names

The validator extracts the base and head branch names from the PR

2

Validate Base Branch

If base branch rules are specified, checks if the base branch matches requirements

3

Validate Head Branch

If head branch rules are specified, checks if the head branch matches requirements

4

Return Result

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

​
Practical Use Cases

​
GitFlow Branch Validation

Enforce GitFlow workflow branch naming:

ruleset:
  - name: "GitFlow Branch Names"
    when:
      - "pull_request.opened"
    validate:
      - type: "branch"
        base:
          match: ["main", "develop", "release-.*"]
          message: "Base branch must be main, develop, or a release branch"
        head:
          match: "^(feature|bugfix|hotfix|release)/[a-z0-9-_]+"
          message: "Branch names must follow GitFlow convention: type/description"
    on_failure:
      - comment:
          body: |
            ## Invalid Branch Name

            Please follow our GitFlow branch naming conventions:

            - Feature branches: `feature/description`
            - Bug fixes: `bugfix/description`
            - Hotfixes: `hotfix/description`
            - Release branches: `release/version`

            {{ validation_summary }}

​
Jira Issue References

Enforce Jira issue IDs in branch names:

validate:
  - type: "branch"
    head:
      match: "^(feature|bugfix|hotfix)/[A-Z]+-[0-9]+-[a-z0-9-]+"
      message: "Branch name must include Jira issue ID (e.g., feature/PROJ-123-description)"

​
Different Rules by Team

Apply different branch naming rules for different parts of the codebase:

ruleset:
  - name: "Frontend Branch Names"
    when:
      - "pull_request.opened"
    if:
      - type: "files"
        modified:
          match: "frontend/.*"
    validate:
      - type: "branch"
        head:
          match: "^frontend/(feature|bugfix)/[a-z0-9-_]+"
    on_failure:
      - comment:
          body: "Frontend branches should follow pattern: frontend/type/description"

  - name: "Backend Branch Names"
    when:
      - "pull_request.opened"
    if:
      - type: "files"
        modified:
          match: "backend/.*"
    validate:
      - type: "branch"
        head:
          match: "^backend/(feature|bugfix)/[a-z0-9-_]+"
    on_failure:
      - comment:
          body: "Backend branches should follow pattern: backend/type/description"

​
Best Practices

Document your branch naming conventions in your contributing guidelines
Use clear, descriptive patterns that communicate the intent
Consider your Git workflow (GitFlow, GitHub Flow, etc.) when defining conventions
Provide helpful error messages explaining the expected format

Be aware that branch names are case-sensitive in Git/GitHub

​
Branch Naming Strategy Tips

Effective branch names should:

  1. Indicate purpose: Use prefixes like feature/, bugfix/, hotfix/
  2. Reference context: Include ticket numbers or brief descriptions
  3. Use separators consistently: Choose either hyphens or underscores
  4. Be reasonably concise: Avoid overly long branch names
  5. Avoid spaces and special characters: Use dashes or underscores instead