conventional-pull-request-action

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

Usage

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).

Configuration

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@v4
      # 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:
          commitlintRulesPath: './commitlint.rules.js' # default: undefined
          # to override config-conventional rules, specify a relative path to your rules module, actions/checkout is required for this setting!
          # if the PR contains a single commit, fail if the commit message and the PR title do not match
          commitTitleMatch: 'true' # default: 'true'
          # if you squash merge PRs and enabled "Default to PR title for squash merge commits", you can disable all linting of commits
          ignoreCommits: 'false' # default: 'false'

Rule Overrides

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

export default {
  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

export default {
  extends: ['@commitlint/config-conventional', './commitlint.rules.js']
}

Contributing

How to contribute

Dev

Install

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.

Release

We use Release Please to automate releases.

Once feature/bugfix/etc PRs are merged, a Release Pull Request should be automatically created, approve the PR and merge.

FAQ

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

To disable all linting of commits and only lint your PR title, set ignoreCommits: 'true', see configuration

Contributors

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