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

#	Name	Type	Default	Description
1	fail_on_error	Boolean	true	Whether the GitHub Action should fail if commitlint detects an issue.
2	verbose	Boolean	false	Enables verbose output.
3	max_header_length	Number		Optional. Maximum header length to check. If not specified, the header length is not checked.
4	token	String	secrets.GITHUB_TOKEN	GitHub Token for fetching commits using the GitHub API.

GitHub Action Outputs

#	Name	Type	Description
1	exit_code	Integer	The exit code of the commitlint step.
2	status	String	The outcome of the commitlint step (success or failure).

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.