Conventional Commitlint

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.

Usage

GitHub Actions

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.

GitHub Action Permissions

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'}

GitHub Action Inputs

GitHub Action Outputs

Pre-commit

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.

CLI (Command Line Interface)

For CLI usage, please refer to cli.md.

Contribution

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