commitlint-github-action

When using GitHub's merge queue feature, you must configure your workflow to listen for the merge_group event with the checks_requested type.

Important Requirement: For the merge queue to function correctly, you must have at least one other workflow that responds to the pull_request event containing a job named exactly commitlint. This satisfies the merge queue's requirement for status checks from the pull request context.

name: Lint Commit Messages in Merge Queue

on:
  merge_group:
    types:
      - checks_requested

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.sha }}

      - uses: wagoid/commitlint-github-action@v6

To lint Pull Request commits, create a GitHub workflow file (e.g., .github/workflows/commitlint.yml) that uses wagoid/commitlint-github-action@v6. You must ensure the workflow has the necessary permissions to read contents and pull requests.

You can trigger this on pull_request events to lint PR commits, or on push events to lint the commits in the push. You can also combine both triggers in a single workflow.

name: Lint Commit Messages
on: [pull_request]

permissions:
  contents: read
  pull-requests: read

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: wagoid/commitlint-github-action@v6

To enable merge queues for your repository:

1. Navigate to Settings > Branches.
2. Under Branch protection rules, edit the rule for your target branch (e.g., master).
3. Enable Require merge queue.
4. Specify commitlint (or your specific job name) as a required status check that must pass before merging.

The action is a Docker action and comes pre-packed with several popular shared configurations (like @commitlint/config-angular and @commitlint/config-conventional).

To use additional dependencies or custom plugins not included in the action, you must install them in your workflow (e.g., via npm install) and then set the NODE_PATH environment variable to point to your repository's node_modules directory.

name: Lint Commit Messages
on: [pull_request]

permissions:
  contents: read
  pull-requests: read

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install
      - uses: wagoid/commitlint-github-action@v6
        env:
          NODE_PATH: ${{ github.workspace }}/node_modules

The action provides a results output containing the error and warning messages for each analyzed commit in JSON format. This is useful for downstream jobs that need to process linting results.

[
  {
    "hash": "cb0f846f13b490c2fd17bd5ed0b6f65ba9b86c75",
    "message": "wrong message",
    "valid": false,
    "errors": ["subject may not be empty", "type may not be empty"],
    "warnings": [],
  },
  {
    "hash": "cb14483cbde23b61322ffb8d3fcdcdc87f514a3141",
    "message": "chore: my message\n\nsome context without leading blank line",
    "valid": true,
    "errors": [],
    "warnings": ["body must have leading blank line"],
  }
]