Conventional Commitlint

PyPI version CI status Downloads codecov License

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:

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.

Project links

Data verified by PyPI on Jul 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aj3sh from gravatar.com aj3sh

Credits

Author: Ajesh Sen Thapa

GitHub Statistics

Data verified by PyPI on Jul 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 (GPLv3) (GPL-3.0)

Requires

Python >=3.10

Tags

commitlint commit lint python commitlint conventional commit conventional commit message python commit github actions pre-commit

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

commitlint-2.0.0.tar.gz (24.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

commitlint-2.0.0-py3-none-any.whl (27.7 kB view details)

Uploaded Python 3

File details

Details for the file commitlint-2.0.0.tar.gz.

File metadata

  • Download URL: commitlint-2.0.0.tar.gz
  • Upload date:
  • Size: 24.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for commitlint-2.0.0.tar.gz
Algorithm Hash digest
SHA256 83ec24f17d87184b4697a8b1d9fe24952888bd40387f8f8c53486584eac960e7
MD5 787ace95a5f2145eb0ef0ac290c3736d
BLAKE2b-256 dd683ed72489311b4b0c985dba1c0fa8ef98c1a6a4d9d14fbac28de15c7e2e6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for commitlint-2.0.0.tar.gz:

Publisher: release-please.yml on opensource-nepal/commitlint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file commitlint-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: commitlint-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 27.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for commitlint-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f3aa539348393bc5e1f346e41bb9a6eb42b20763df8d0d528eaf1b29284c2510
MD5 00817c996284dae20477054469195fab
BLAKE2b-256 967e224f9ba092d1374869c512f49b4e30905424867d70a7f4dede7f44cf8f5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for commitlint-2.0.0-py3-none-any.whl:

Publisher: release-please.yml on opensource-nepal/commitlint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page