Validate Commit Messages in Pull Requests

This repository implements a reusable GitHub Action that validates commit messages in pull requests on GitHub to ensure that the commit messages meet certain standards and to remind you about squash commits that must be consolidated before you merge the pull request.

It checks the commits that are about to be delivered to the target branch. It does not check any commits outside the pull request such as existing commits that have already been merged to the target branch in a previous pull request.

Usage

Basic Example

# .github/workflows/ci.yml

name: CI

on:
  pull_request:
    branches:
      - main

jobs:
  has-standardised-commit-messages:
    name: Has standardised commit messages
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-24.04
    timeout-minutes: 1
    permissions:
      pull-requests: read # Allow `rainstormy/github-action-validate-commit-messages` to read the commit messages in the pull request.
    steps:
      - name: Verify that the commit messages are standardised
        uses: rainstormy/github-action-validate-commit-messages@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          rules: |
            no-merge-commits,
            no-squash-commits,

Advanced Example

This example uses all the available rules and tweaks the configuration of a subset of the rules.

# .github/workflows/ci.yml

name: CI

on:
  pull_request:
    branches:
      - main

jobs:
  has-standardised-commit-messages:
    name: Has standardised commit messages
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-24.04
    timeout-minutes: 1
    permissions:
      pull-requests: read # Allow `rainstormy/github-action-validate-commit-messages` to read the commit messages in the pull request.
    steps:
      - name: Verify that the commit messages are standardised
        uses: rainstormy/github-action-validate-commit-messages@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          rules: |
            acknowledged-author-email-addresses,
            acknowledged-author-names,
            acknowledged-committer-email-addresses,
            acknowledged-committer-names,
            capitalised-subject-lines,
            empty-line-after-subject-lines,
            imperative-subject-lines,
            limit-length-of-body-lines,
            limit-length-of-subject-lines,
            multi-word-subject-lines,
            no-co-authors,
            no-merge-commits,
            no-revert-revert-commits,
            no-squash-commits,
            no-trailing-punctuation-in-subject-lines,
            no-unexpected-whitespace,
            unique-subject-lines,
          # The author and committer email address must be on the form `id+username@users.noreply.github.com` or `noreply@github.com` (only for reverting pull requests).
          acknowledged-author-email-addresses--patterns: '\d+\+.+@users\.noreply\.github\.com'
          acknowledged-committer-email-addresses--patterns: '\d+\+.+@users\.noreply\.github\.com noreply@github\.com'
          # The author and committer name must consist of at least two words where the first word starts with a capital letter, or it should be 'GitHub' (only for reverting pull requests).
          acknowledged-author-names--patterns: '\p{Lu}.*\s.+'
          acknowledged-committer-names--patterns: '\p{Lu}.*\s.+ GitHub'
          # The subject line must include a GitHub issue reference as a suffix.
          issue-references-in-subject-lines--allowed-positions: as-suffix
          issue-references-in-subject-lines--patterns: '\(#[1-9][0-9]*\) #[1-9][0-9]*'

Rules

Key	Description
acknowledged-author-email-addresses	The commit author must use an email address that matches a given regular expression.
acknowledged-author-names	The commit author must use a name that matches a given regular expression.
acknowledged-committer-email-addresses	The committer must use an email address that matches a given regular expression.
acknowledged-committer-names	The committer must use a name that matches a given regular expression.
capitalised-subject-lines	The subject line must start with an uppercase letter.
empty-line-after-subject-lines	The subject line and the message body must be separated by an empty line.
imperative-subject-lines	The subject line must start with a verb in the imperative mood.
issue-references-in-subject-lines	The subject line must contain a reference to an issue tracking system.
limit-length-of-body-lines	Each line in the message body must not exceed a given number of characters.
limit-length-of-subject-lines	The subject line must not exceed a given number of characters.
multi-word-subject-lines	The subject line must contain at least two words.
no-co-authors	The message body must not contain Co-authored-by: trailers.
no-merge-commits	Disallow merge commits to be merged to the target branch.
no-revert-revert-commits	Disallow commits that revert other revert commits to be merged to the target branch.
no-squash-commits	Disallow squash commits to be merged to the target branch.
no-trailing-punctuation-in-subject-lines	The subject line must not end with a punctuation character.
no-unexpected-whitespace	The subject line and message body must not contain any leading, trailing, or consecutive whitespace characters.
unique-subject-lines	Disallow commits that repeat the subject line of a previous commit in the pull request to be merged to the target branch.