A github action that enforces the conventional commit spec on pull requests to ensure a clean and conventional commit history.

Proudly built by:

• Usage

  • Configuration
  • Rule Overrides

• Contributing

  • Develop
    • Install
  • Releasing

• FAQ

This action uses commitlint with the config-conventional configuration to ensure merge commits meet the conventional commit spec.

This action lints the pull request's title, and in the case of a PR with a single commit, the commit message (see FAQ for details).

Create a github action workflow:

# .github/workflows/conventional-pr.yml

name: conventional-pr
on:
  pull_request:
    branches:
      - main
      - master
    types:
      - opened
      - edited
      - synchronize
jobs:
  lint-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # check for the most recent release: https://github.com/CondeNast/conventional-pull-request-action/releases
      # replace vX.X.X below with the most recently released version
      - uses: CondeNast/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          # to override config-conventional rules, specify a relative path to your rules module, actions/checkout is required for this setting!
          commitlintRulesPath: "./commitlint.rules.js" # default: undefined
          # if the PR contains a single commit, fail if the commit message and the PR title do not match
          commitTitleMatch: "true" # default: 'true'

This action supports overriding rules from config-conventional (see this repo as an example):

Your rules file must export an object with a rules field, other commitlint configuration fields are not supported.

// ./commitlint.rules.js

module.exports = {
  rules: {
    ...
  }
}

If you use commitlint in your git hooks, you can extend your custom rules in your commitlint.config.js so the commitlint rules config is shared between your hook and this action, ex: commitlint.config.js

// ./commitlint.config.js

module.exports = {
  extends: ["@commitlint/config-conventional", "./commitlint.rules.js"],
};

How to contribute

nvm use
npm i

Github javascript actions require all dependencies to be checked into the codebase, so we use ncc to compile all dependencies and source code into a single file. To make changes to this action, compile and commit:

npm run prepare
git add .
git commit

Be sure to commit and push all changed files in ./dist to see your changes to the action execute.

From the up-to-date main branch:

npm run release
git push --follow-tags

1. Why is my commit required to conform with the spec?

In the case of pull requests with a single commit, when a developer merges the PR, github will autofill the merge commit message with the PR's commit message, instead of the PR's title. By enforcing the spec on the single commit, the pre-populated merge commit message will conform to the spec.

2. Why must my commit message match the PR title?

In the case of pull requests with a single commit, the commit message will be used as the merge commit message. In PRs with multiple commits, the PR title is used as the merge commit message. By enforcing a commit message/PR title match, we ensure a merge commit message will always match a PR title, no matter how many commits are included in a pull request.

To disable this behavior set commitTitleMatch: 'false', see configuration

See the list of contributors who participated in writing this tool.