gommitlint-action

GitHub Action to validate git commit messages using gommitlint.

Quick Start

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    base-branch: main

Inputs

Input	Description	Required	Default
config	Path to gommitlint configuration file	No	-
base-branch	Base branch to compare against (comma-separated for fallback, e.g., main,master,develop)	No	-
range	Commit range to validate (e.g., HEAD~5..HEAD, main..HEAD)	No	-
count	Validate last N commits from HEAD	No	-
rules	Only validate specific rules (comma-separated)	No	-
exclude-rules	Exclude specific rules (comma-separated)	No	-
format	Output format: text, json, forgejo, github, gitlab	No	github
verbose	Increase output verbosity for debugging	No	false
log-level	Log level: error, warn, info, debug, trace	No	-
skip-verification	Skip binary checksum verification (not recommended)	No	false
no-ci-detect	Disable automatic CI environment detection	No	false

Note: Use either base-branch, range, OR count - not multiple.

Examples

Validate PR Commits

name: Validate Commits

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history needed for commit comparison

      - uses: itiquette/gommitlint-action@v0.9.10
        with:
          range: ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}

Validate Last N Commits

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    count: 5

Validate Commit Range

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    range: HEAD~5..HEAD

Only Check Conventional Commits

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    base-branch: main
    rules: conventional

Skip Signature Checks

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    base-branch: main
    exclude-rules: cryptosignature,signoff

Allow Merge Commits

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    base-branch: main
    exclude-rules: linearhistory

With Configuration File

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    config: .gommitlint.yaml
    base-branch: main

Configuration

For advanced options like ignore_commits, allow_fixup_commits, spell checking, and more, use a .gommitlint.yaml configuration file. See the gommitlint documentation for all available options.

Troubleshooting

"fatal: bad revision" Error

This occurs when git can't find a referenced commit or branch. For base-branch: main or range: main..HEAD:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history needed for commit comparison

- run: git fetch origin main:main  # Fetch main branch ref (not available in PR context)

- uses: itiquette/gommitlint-action@v0.9.10
  with:
    base-branch: main

Validation Fails on Merge Commits

The LinearHistory rule (enabled by default) rejects merge commits to enforce a rebase workflow. If disabled, merge commits are simply skipped by other rules - they pass through without validation.

To allow merge commits, disable the rule in your .gommitlint.yaml:

gommitlint:
  rules:
    disabled:
      - linearhistory

Recommended Permissions

The action only requires read access to repository contents:

permissions:
  contents: read

Related Projects

• gommitlint - The commit message linter itself
• gommitlint-action (Forgejo) - A Forgejo Actions version of this

License

EUPL-1.2