amannn/action-semantic-pull-request

Validate that PR titles follow the Conventional Commits spec before they can merge.

Community actionCategory: Pull Request AutomationLatest v6View on GitHub

What it does

amannn/action-semantic-pull-request checks that the PR title parses as a Conventional Commit (type(scope): subject), which matters when you squash-merge and the PR title becomes the commit message.

Types, scopes, and the subject format are all configurable with regex patterns, and validation can be skipped via labels or a [WIP] prefix.

Usage

workflow (.yml)

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

Inputs

Input	Description	Default	Required
`types`	Custom allowed types (newline delimited) instead of the Conventional Commits defaults. Regex patterns auto-wrapped in ^ $.	-	No
`scopes`	Which scopes are allowed (newline delimited). Regex patterns auto-wrapped in ^ $.	-	No
`requireScope`	Configure that a scope must always be provided.	-	No
`subjectPattern`	Additional regex validation for the subject, e.g. ^(?![A-Z]).+$ to forbid a leading uppercase character.	-	No
`validateSingleCommit`	Also validate the commit message on single-commit PRs, since GitHub suggests it as the squash-merge message.	-	No
`ignoreLabels`	Skip validation when the PR has one of these labels (newline delimited).	-	No

Notes

The token is passed as the GITHUB_TOKEN environment variable, not a with: input.

Trigger on opened, edited, and synchronize so the check re-runs when the title is fixed; add labeled/unlabeled if you use ignoreLabels.

Common errors

A failure listing "No release type found..." or an unknown type means the PR title's type is not in the allowed set; fix the title (e.g. feat: ...) or extend types.
The check not re-running after a title edit means the workflow is missing the edited activity type on the pull_request trigger.

Security and pinning

The action only needs to read the PR; keep permissions at pull-requests: read and pin to a commit SHA.

Alternatives and related

peter-evans/create-or-update-commentCreate a new comment, or append to / replace an existing one, on an issue or pull request. actions/labelerAutomatically label pull requests based on the files they change.

Frequently asked questions

Why validate the PR title instead of every commit?

With squash merging, the PR title becomes the commit message on the default branch, so linting the title is enough to keep history Conventional-Commits-clean without policing every intermediate commit.

References

GitHub Actions documentation