Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
shield

GitHub Action

semantic-pull-request

v4.5.0

semantic-pull-request

shield

semantic-pull-request

Ensure your PR title matches the Conventional Commits spec (https://www.conventionalcommits.org/)

Installation

Copy and paste the following snippet into your .yml file.

              

- name: semantic-pull-request

uses: amannn/action-semantic-pull-request@v4.5.0

Learn more about this action in amannn/action-semantic-pull-request

Choose a version

action-semantic-pull-request

This is a GitHub Action that ensures that your PR title matches the Conventional Commits spec.

This is helpful when you're using semantic-release with the Conventional Commits preset. When using the "Squash and merge" strategy, GitHub will suggest to use the PR title as the commit message. With this action you can validate that the PR title will lead to a correct commit message and subsequently the expected release.

Validation

Examples for valid PR titles:

  • fix: Correct typo.
  • feat: Add support for Node 12.
  • refactor!: Drop support for Node 6.
  • feat(ui): Add Button component.

Note that since PR titles only have a single line, you have to use the ! syntax for breaking changes.

See Conventional Commits for more examples.

Example config

name: "Lint PR"

on:
  pull_request_target:
    types:
      - opened
      - edited
      - synchronize

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

Configuration

The action works without configuration, however you can provide options for customization.

        with:
          # Configure which types are allowed.
          # Default: https://github.com/commitizen/conventional-commit-types
          types: |
            fix
            feat
          # Configure which scopes are allowed.
          scopes: |
            core
            ui
          # Configure that a scope must always be provided.
          requireScope: true
          # Configure which scopes are disallowed in PR titles. For instance,  by setting
          # the value below, `chore(release): ...` or `ci(e2e,release): ...` will be rejected.
          disallowScopes: |
            release
          # Configure additional validation for the subject based on a regex.
          # This example ensures the subject doesn't start with an uppercase character.
          subjectPattern: ^(?![A-Z]).+$
          # If `subjectPattern` is configured, you can use this property to override
          # the default error message that is shown when the pattern doesn't match.
          # The variables `subject` and `title` can be used within the message.
          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.
          # When using "Squash and merge" on a PR with only one commit, GitHub
          # will suggest using that commit message instead of the PR title for the
          # merge commit, and it's easy to commit this by mistake. Enable this option
          # to also validate the commit message for one commit PRs.
          validateSingleCommit: true
          # Related to `validateSingleCommit` you can opt-in to validate that the PR
          # title matches a single commit to avoid confusion.
          validateSingleCommitMatchesPrTitle: true
          # If you use GitHub Enterprise, you can set this to the URL of your server
          githubBaseUrl: https://github.myorg.com/api/v3
          # If the PR contains one of these labels, the validation is skipped.
          # Multiple labels can be separated by newlines.
          # If you want to rerun the validation when labels change, you might want
          # to use the `labeled` and `unlabeled` event triggers in your workflow.
          ignoreLabels: |
            bot
            ignore-semantic-pull-request
          # If you're using a format for the PR title that differs from the traditional Conventional
          # Commits spec, you can use these options to customize the parsing of the type, scope and
          # subject. The `headerPattern` should contain a regex where the capturing groups in parentheses
          # correspond to the parts listed in `headerPatternCorrespondence`.
          # See: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#headerpattern
          headerPattern: '^(\w*)(?:\(([\w$.\-*/ ]*)\))?: (.*)$'
          headerPatternCorrespondence: type, scope, subject
          # For work-in-progress PRs you can typically use draft pull requests 
          # from GitHub. However, private repositories on the free plan don't have 
          # this option and therefore this action allows you to opt-in to using the 
          # special "[WIP]" prefix to indicate this state. This will avoid the 
          # validation of the PR title and the pull request checks remain pending.
          # Note that a second check will be reported if this is enabled.
          wip: true

Event triggers

There are two events that can be used as triggers for this action, each with different characteristics:

  1. pull_request_target: This allows the action to be used in a fork-based workflow, where e.g. you want to accept pull requests in a public repository. In this case, the configuration from the main branch of your repository will be used for the check. This means that you need to have this configuration in the main branch for the action to run at all (e.g. it won't run within a PR that adds the action initially). Also if you change the configuration in a PR, the changes will not be reflected for the current PR – only subsequent ones after the changes are in the main branch.
  2. pull_request: This configuration uses the latest configuration that is available in the current branch. It will only work if the branch is based in the repository itself. If this configuration is used and a pull request from a fork is opened, you'll encounter an error as the GitHub token environment parameter is not available. This option is viable if all contributors have write access to the repository.