https://github.com/opensource-nepal/commitlint
Lint Conventional Commit message on GitHub Actions and pre-commit.
https://github.com/opensource-nepal/commitlint
actions commit commit-lint commit-message commitlint conventional conventional-commit git github-actions hooks pr pre-commit pre-commit-hook pull-requests python python-commitlint semantic-commit
Last synced: 4 months ago
JSON representation
Lint Conventional Commit message on GitHub Actions and pre-commit.
- Host: GitHub
- URL: https://github.com/opensource-nepal/commitlint
- Owner: opensource-nepal
- License: gpl-3.0
- Created: 2024-01-12T09:59:56.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-24T03:03:17.000Z (4 months ago)
- Last Synced: 2025-08-24T06:00:50.862Z (4 months ago)
- Topics: actions, commit, commit-lint, commit-message, commitlint, conventional, conventional-commit, git, github-actions, hooks, pr, pre-commit, pre-commit-hook, pull-requests, python, python-commitlint, semantic-commit
- Language: Python
- Homepage:
- Size: 136 KB
- Stars: 32
- Watchers: 2
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Conventional Commitlint
[](https://badge.fury.io/py/commitlint)
[](https://github.com/opensource-nepal/commitlint/actions)
[](https://pypi.org/project/commitlint/)
[](https://codecov.io/github/opensource-nepal/commitlint)
[](https://github.com/opensource-nepal/commitlint/blob/main/LICENSE)
`commitlint` is a tool that lints commit messages according to the [Conventional Commits](./docs/conventional-commits.md) 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:
```yaml
...
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.yaml`:
```yaml
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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-default-github_token-permissions), or
- the [workflow/job permissions block](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions)
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 | **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`:
```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:
```bash
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](./docs/cli.md).
## Contribution
We appreciate feedback and contributions to this package. To get started, please see our [contribution guide](./CONTRIBUTING.md).