How to Use the semantic-pull-request GitHub Action to Ensure Conventional Commits

name: 'Usage of action-semantic-pull-request GitHub Action'
on:
  pull_request_target:
    types:
      - opened
      - edited
      - synchronize

permissions:
  pull-requests: read

jobs:
  main:
    name: Validate PR title
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Semantic Pull Request

A GitHub Action that ensures that your PR title matches the Conventional Commits spec.

What is Semantic Pull Request?​

If you would like to enhance this GitHub Flow with pull requests that have a title following the Conventional Commits specification, use the semantic-pull-request GitHub Action. This guide will explain what this action is all about, how to configure it and optionally, what features it offers.

How to Configure Allowed Types​

You can specify which commit types are allowed. This helps ensure that only specific types of changes are permitted.

with:
  types: |
    fix
    feat

How to Configure Allowed Scopes​

Define regex patterns for allowed scopes. This ensures that your commit messages contain relevant scopes.

with:
  scopes: |
    core
    ui
    JIRA-\d+

How to Require Scopes​

Set requireScope to true if a scope must always be provided in your commit messages.

with:
  requireScope: true

How to Disallow Specific Scopes​

Define regex patterns for scopes that should be disallowed. This helps prevent certain scopes from being used in your commit messages.

with:
  disallowScopes: |
    release
    [A-Z]+

How to Enforce a Subject Pattern​

Use a regex to enforce specific patterns for the subject. For example, this ensures the subject doesn’t start with an uppercase character.

with:
  subjectPattern: ^(?![A-Z]).+$

How to Customize the Subject Pattern Error Message​

Customize the error message for subjectPattern violations to provide clearer guidance to your team.

with:
  subjectPatternError: |
    The subject "{subject}" found in the pull request title "{title}"
    didn't match the configured pattern. Please ensure that the subject
    doesn't start with an uppercase character.

How to Override the GitHub Base URL​

Override the GitHub base URL if necessary, although this is generally not recommended.

with:
  githubBaseUrl: https://github.myorg.com/api/v3

How to Ignore Specific Labels​

Skip validation for PRs with specific labels. This can be useful for excluding certain PRs from the validation process.

with:
  ignoreLabels: |
    bot
    ignore-semantic-pull-request

How to Customize the Header Pattern​

If your PR title format differs from the traditional Conventional Commits spec, customize the parsing of the type, scope, and subject.

with:
  headerPattern: '^(\w*)(?:$begin:math:text$([\\w$.\\-*/ ]*)$end:math:text$)?: (.*)$'
  headerPatternCorrespondence: type, scope, subject