How to Require a Conventional Commit PR Title Check

A pull request title lint validates the title against Conventional Commits and reports a status the branch can require.

Because a squash merge uses the PR title as the commit subject, a title check keeps the history and changelog consistent. Run it on the pull request and make it a required status check.

Steps

• Add a workflow that lints the PR title on pull_request.
• Report a check the branch protection rule requires.
• Enable "Require status checks" and list the title check.

Workflow

on:
  pull_request:
    types: [opened, edited, synchronize]
permissions:
  pull-requests: read
jobs:
  pr-title:
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gotchas

• A PR title check runs on pull_request, not on the merge group; do not require it on the queue or it will hang as "Expected".
• Editing the title re-runs the check because of the edited type.

Related guides