commitlint is a tool that lints commit messages according to the Conventional Commits standard. It can be used in GitHub Actions and as a pre-commit hook.

If you have an existing workflow, add the following steps:

...
steps:
    ...

    - name: Conventional Commitlint
      uses: opensource-nepal/commitlint@v1

    ...

If you don't have any workflows, create a new GitHub workflow file, e.g., .github/workflows/commitlint.yml:

name: Conventional Commitlint

on:
  push:
    branches: ["main"]
  pull_request:

jobs:
  commitlint:
    runs-on: ubuntu-latest
    name: Conventional Commitlint
    permissions:
      contents: read
      pull-requests: read
    steps:
      - name: Conventional Commitlint
        uses: opensource-nepal/commitlint@v1

Note: The commitlint GitHub Action is triggered only by push, pull_request, or pull_request_target events.

The action requires read permission for the following scopes:

• contents: read : This allows the action to list commits of the repository.
• pull-requests: read : This allows the action to list the commits in a Pull Request.

For public repositories, these permissions are granted by default. For private repositories, you must explicitly grant them, either in:

• the repository’s default workflow permissions, or
• the workflow/job permissions block

Without these, you may encounter an error like:

Github API failed with status code 403. Response: {'message': 'Resource not accessible by integration', 'documentation_url': 'https://docs.github.com/rest/pulls/pulls#list-commits-on-a-pull-request', 'status': '403'}

1. Add the following configuration to .pre-commit-config.yaml:

   repos:
      ...
      - repo: https://github.com/opensource-nepal/commitlint
        rev: v1.3.0
        hooks:
          - id: commitlint
      ...

2. Install the commit-msg hook in your project repository:

   pre-commit install --hook-type commit-msg

   Running only pre-commit install will not work.

Note: Avoid using commit messages that start with #, as this may cause unexpected behavior with commitlint.

For CLI usage, please refer to cli.md.

We appreciate feedback and contributions to this package. To get started, please see our contribution guide.