Sheriff is a GitHub Action that patrols your pull requests and ensures titles follow a strict format. Perfect for enforcing Conventional Commits or your own custom rules.

No more wild, lawless PR titles - the Sheriff keeps things tidy.

• Enforces the type(scope): message format
• Supports multiple scopes - type(scope1|scope2): message
• Detects breaking changes (!) and checks if they’re allowed
• Fully configurable types & scopes
• Flexible input formats for types and scopes (comma, newline, arrays, pipes)
• Instantly fails CI if rules are broken
• Works in any PR workflow

Follow these steps and your repo will be safer than a vault in Fort Knox.

1. Star the repo - show the Sheriff some love before he starts working 😁.

2. Create a workflow file .github/workflows/check-pr-title.yml.

3. Copy this template into your file:

   name: PR Title Check
   
   on:
     pull_request:
       types: [opened, edited, synchronize]
   
   jobs:
     sheriff:
       runs-on: ubuntu-latest
       steps:
         - name: Validate PR title
           uses: teneplaysofficial/sheriff@v3
           with:
             types: [feat, fix, docs, ci, test, chore]
             scopes: |
               core
               api
               ui
               docs
             allow_breaking: true
             enforce_scopes: true

4. Commit & push - the Sheriff is now on duty. Any outlaw PR title will be gunned down.

All of these work for types or scopes:

# Comma-separated
types: feat,fix,docs

# Pipe-separated
types: feat|fix|docs

# Multiline block
scopes: |
  core
  api
  ui

# YAML array
scopes: [core, api, ui]

# JSON array (quoted)
types: '["feat","fix","docs"]'

Sheriff-approved examples:

• feat(api): add authentication support
• fix(core|ui): resolve dark mode toggle bug
• docs: update contributing guide

Titles that’ll land you in PR jail:

• feature: add new login page - type not allowed
• fix(auth): - message empty
• performance(core): rename variables - type not in allowed list

1. Sheriff loads default types and scopes from JSON files.
2. If you give workflow inputs, they override the defaults.
3. Inputs are normalized with parseList, supporting commas, pipes, YAML arrays, JSON arrays, or multiline blocks.
4. The PR title is checked against the Sheriff’s regex badge.
5. PR is marked invalid if:
   • Type is not allowed
   • Scope is not allowed (only when enforce_scopes is true)
   • Breaking change (!) is present but disallowed
   • Message is empty

Released under the Apache-2.0 License.

The Sheriff works free of charge, but tips are appreciated in the form of stars.