Skip to content

Action #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coolapso merged 4 commits into from
May 31, 2025
Merged

Action #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c3771ca
docs: Add demo gif
coolapso May 31, 2025
11ac293
fix(action): Properly fetch git history
coolapso May 31, 2025
1e29c0f
ci(test): Run workflow directly from repository
coolapso May 31, 2025
b5473f2
docs(readme): Add more details
coolapso May 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/test.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@main
continue-on-error: true
- uses: ./
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

238 changes: 162 additions & 76 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,147 +3,233 @@
</p>

# CONVCOMMITLINT

[![Release](https://github.com/coolapso/convcommitlint/actions/workflows/release.yaml/badge.svg?branch=main)](https://github.com/coolapso/convcommitlint/actions/workflows/release.yaml)
![GitHub Tag](https://img.shields.io/github/v/tag/coolapso/convcommitlint?logo=semver&label=semver&labelColor=gray&color=green)
[![Docker image version](https://img.shields.io/docker/v/coolapso/convcommitlint/latest?logo=docker)](https://hub.docker.com/r/coolapso/convcommitlint)
[![Go Report Card](https://goreportcard.com/badge/github.com/coolapso/convcommitlint)](https://goreportcard.com/report/github.com/coolapso/convcommitlint)
![GitHub Sponsors](https://img.shields.io/github/sponsors/coolapso?style=flat&logo=githubsponsors)

A simple, slightly opinionated, yet usable linter for [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), written in Go.
This linter covers the convention essentials, contributions are wellcome but, no! I don't intend to support all kinds of variations and custom rules!
A simple, slightly opinionated, but actually *usable* linter for [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), written in Go.

---

## Motivation

I just wanted something simple that works, not configure all kinds of things just to get a linter working!
I just wanted something that *works* out of the box. No over-configuration, no headaches—just simple commit linting! This being said, this linter covers the essentials. Contributions are welcome, but I don’t intend to support every possible variation or custom rule!

---

## Features

* Checks for header syntax
* Checks for common typos on the most important keywords: fix, feat and BREAKING CHANGE
* Supports creating pull github pull request reviews
* Supports request for changes (default)
* Supports commenting only
* Supports linting only the current commit
* Supports linting all commits
* Supports linting only most recent commits from base branch
- **Checks header syntax**
- **Detects common typos** in key keywords: `fix`, `feat`, and `BREAKING CHANGE`
- **GitHub Pull Request Reviews:**
- Request changes (default)
- Comment-only mode
- **Lint Modes:**
- Lint only the current commit
- Lint all commits
- Lint only recent commits from the base branch
- **Full environment variable support** for all flags
- **Cross-platform:** Linux, macOS, and Windows
- **GitHub Action** support

## How it works
---

convcommitlint will check your commits against the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, and let you know if there are any issues, when running on github actions and if you enable creation of pull request reviews it will create a pull request review for you.
## How It Works

## Installation
`convcommitlint` checks your commits against the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
If you use it as a GitHub Action or enable PR review, it will comment or request changes directly on your pull requests, listing any issues it finds.

### Github action
---

Github action is available to use with your CI pipelines and most arguments from the CLI application are available.
## Usage

```
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
convcommitlint [flags]
convcommitlint [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
version Print convcommitlint version

Flags:
-b, --base-branch string The base branch to check commits from (default "main")
--comment-only Pull request reviews will only comment instead of requesting changes
-r, --create-review Creates review on github pull request
-c, --current Lint only the current commit
-h, --help help for convcommitlint
-a, --lint-all Lint all repository commits
-p, --path string Git repository path (default "./")
--pr-number int The number of pull request to create the review
--repository string The github repository in owner/name format ex: coolapso/convcommitlint

Use "convcommitlint [command] --help" for more information about a command.
```
<p align="center">
<img src="https://raw.githubusercontent.com/coolapso/convcommitlint/refs/heads/main/images/demo.gif">
</p>

You can find the available inputs in the [action.yaml](action.yaml) file, if a input is not available you still should be able to use it by setting the associated ENV variable.

> [!IMPORTANT]
> Be sure to include the Checkout in your workflow, this action won't do it for you!
### Environment Variables

### Docker
Every flag can also be set with an environment variable, using the `CONVCOMMITLINT_` prefix, uppercase, and underscores.
For example, the flag `--lint-all` becomes the variable `CONVCOMMITLINT_LINT_ALL`.

---

You can run convcommitlint with docker, containers are provided both on dockerhub and ghcr.io
## GitHub Action

**ghcr.io**
You can use `convcommitlint` as part of your CI pipeline. Most CLI arguments are supported as action inputs.

```yaml
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
```
docker run -v $(pwd):/data --rm ghcr.io/coolapso/convcommitlint:latest

### Base Branch

By default, the base branch is `"main"`. If you use a different default branch, set the `base-branch` input:

```yaml
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
with:
base-branch: develop
```

**dockerhub:**
### Git History Depth

By default, the action checks out the reference branch with full history. To limit this, use the `fetch-depth` input (commits beyond this depth will *not* be analyzed):

```yaml
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
with:
fetch-depth: 10
```
docker run -v $(pwd):/data --rm coolapso/convcommitlint:latest

### Disable Pull Request Reviews

PR reviews are enabled by default. To disable them, set `create-review` to `"false"`:

```yaml
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
with:
create-review: "false"
```

### Go Install
### Use a Specific Version

#### Latest version
The action uses the latest release by default. To pin a specific version:

`go install github.com/coolapso/convcommitlint@latest`
```yaml
convcommitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: coolapso/convcommitlint@v0
with:
version: v0.2.0
```

#### Specific version
### Other Features & Flags

`go install github.com/coolapso/convcommitlint@v1.0.0`
The action supports all CLI features and flags.
Check available inputs in [`action.yaml`](action.yaml).
If an input is missing, you can always set the corresponding environment variable.

### AUR
---

On Arch linux you can use the AUR `convcommitlint-bin`
## Installation

### Linux Script
### Docker

It is also possible to install on any linux distro with the installation script
Images are available on both DockerHub and GitHub Container Registry (ghcr.io):

#### Latest version
**GitHub Container Registry:**

```sh
docker run -v $(pwd):/data --rm ghcr.io/coolapso/convcommitlint:latest
```
curl -L http://commitlint.coolapso.sh/install.sh | bash

**DockerHub:**

```sh
docker run -v $(pwd):/data --rm coolapso/convcommitlint:latest
```

#### Specific version
### Go Install

#### Latest Version

```sh
go install github.com/coolapso/convcommitlint@latest
```
curl -L http://commitlint.coolapso.sh/install.sh | VERSION="v1.1.0" bash

#### Specific Version

```sh
go install github.com/coolapso/convcommitlint@v1.0.0
```

### Manual install
### Arch Linux (AUR)

* Grab the binary from the [releases page](https://github.com/coolapso/convcommitlint/releases).
* Extract the binary
* Execute it
On Arch Linux, use the AUR package: `convcommitlint-bin`.

### Linux Install Script

## Usage
Install on any Linux distro using the script:

#### Latest Version

```sh
curl -L http://commitlint.coolapso.sh/install.sh | bash
```
Usage:
convcommitlint [flags]
convcommitlint [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
version Print convcommitlint version
#### Specific Version

Flags:
-b, --base-branch string The base branch to check commits from (default "main")
--comment-only Pull request reviews will only comment instead of requesting changes
-r, --create-review Creates review on github pull request
-c, --current Lint only the current commit
-h, --help help for convcommitlint
-a, --lint-all Lint all repository commits
-p, --path string Git repository path (default "./")
--pr-number int The number of pull request to create the review
--repository string The github repository in owner/name format ex: coolapso/convcommitlint

Use "convcommitlint [command] --help" for more information about a command.
```sh
curl -L http://commitlint.coolapso.sh/install.sh | VERSION="v1.1.0" bash
```

## Build

`go build -o convcommitlint
### Manual Install

# Contributions
- Download the binary from the [releases page](https://github.com/coolapso/convcommitlint/releases)
- Extract the binary
- Run it

Improvements and suggestions are always welcome, feel free to check for any open issues, open a new Issue or Pull Request
### Build

If you like this project and want to support / contribute in a different way you can always [:heart: Sponsor Me](https://github.com/sponsors/coolapso) or
```sh
go build -o convcommitlint
```

<a href="https://www.buymeacoffee.com/coolapso" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/default-yellow.png" alt="Buy Me A Coffee" style="height: 51px !important;width: 217px !important;" />
</a>
---

## Contributions

Improvements and suggestions are always welcome!
Check open issues, or open a new Issue or Pull Request.

Also consider supporting [tapio/live-server](https://github.com/tapio/live-server) which inspired this project
If you like this project and want to support or contribute in another way, you can [:heart: Sponsor Me](https://github.com/sponsors/coolapso) or:

<a href="https://www.buymeacoffee.com/coolapso" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/default-yellow.png" alt="Buy Me A Coffee" style="height: 51px !important;width: 217px !important;" />
</a>
42 changes: 17 additions & 25 deletions action.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,21 @@
name: 'commit lint'
name: 'convcommitlint'
description: 'Check if commits follow the conventional commits standard'
branding:
icon: 'git-commit'
color: 'gray-dark'
inputs:
fetch-depth:
description: 'git fetch depth when checking out the repository'
required: false
default: "0"
base-branch: # id of input
description: 'base branch to lint from'
required: false
default: "main"
comment-only:
description: 'Do not request changes on pull requests'
required: false
default: "false"
create-review:
description: 'Creates a pull request revie'
description: 'Creates a pull request review'
required: false
default: "true"
current:
description: 'Lints only current commit'
required: false
default: "false"
lint-all:
description: 'Lints all commits in the history'
required: false
default: "false"
path:
description: 'Path to the repository'
required: false
default: "./"
version:
description: 'go conventional commit version to run'
required: false
Expand All @@ -39,16 +30,17 @@ runs:
- name: "install conventional commit lint"
shell: bash
run: go install github.com/coolapso/convcommitlint@${{ inputs.version }}
- uses: actions/checkout@v4
with:
fetch-depth: ${{ inputs.fetch-depth }}
ref: ${{ github.head_ref }}
- name: 'get base branch last commit'
run: git fetch origin ${{ inputs.base-branch }}:${{ inputs.base-branch }} --depth 1
shell: bash
- name: "Lint commits"
shell: bash
run: |
export CONVCOMLINT_BASE_BRANCH=${{ inputs.base-branch }}
export CONVCOMLINT_COMMENT_ONLY=${{ inputs.comment-only }}
export CONVCOMLINT_CREATE_REVIEW=${{ inputs.create-review }}
export CONVCOMLINT_CURRENT=${{ inputs.current }}
export CONVCOMLINT_LINT_ALL=${{ inputs.lint-all }}
export CONVCOMLINT_PATH=${{ inputs.path }}
convcommitlint
convcommitlint -b ${{ inputs.base-branch }} --create-review=${{ inputs.create-review }}



Expand Down
Binary file modified images/demo.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading