Lint PR titles, commit messages and PR metadata against Conventional Commits.
No Docker. No Node. No token. One bash script that runs in milliseconds, on GitHub-hosted and self-hosted runners.
- ⚡️ Instant. A composite action with native bash regex matching. No
npm install, no image pull. - 🧩 One action, three checks. PR title, every commit in the range, and required assignee/label.
- 🤖 Bot and draft aware. Dependabot, Renovate,
[bot]accounts and drafts can be skipped. - 🌿 Branch aware. Skip release or bot branches with comma-separated globs such as
release/*,dependabot/*. - 🔠 Style rules. Optional description case and subject length. Emoji are counted as characters, not bytes.
- 💥 Breaking changes. Supports
feat(api)!: drop v1, which most hand-written regexes miss. - 🔍 Real feedback. Each failure says why it failed and what was expected.
- 📊 Step summary. A Markdown table of invalid messages, plus outputs for later steps.
- 🔐 No extra access. No token and no permissions needed. The PR event payload has the labels and assignees.
- 🪶 Portable. Linux, macOS and Windows (Git Bash), bash 3.2+.
name: "🔎 Lint commits"
on:
pull_request:
types: [opened, edited, synchronize, reopened]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0 # Needed to read the base commit
- uses: HarryVasanth/fast-commit-linter@v1
with:
base_sha: ${{ github.event.pull_request.base.sha }}
head_sha: ${{ github.event.pull_request.head.sha }}The PR title defaults to the event title. With base_sha and head_sha set,
every commit in the PR is checked too. Without them, only the title is checked.
To check only a list of messages and skip git, pass commit_messages
instead:
- uses: HarryVasanth/fast-commit-linter@v1
with:
commit_messages: |
feat(api): add login endpoint
fix: handle empty response| Input | Description | Default |
|---|---|---|
pr_title |
🔖 PR title to validate | the event PR title |
check_pr_title |
🔖 Check the PR title | true |
commit_messages |
📝 Newline-separated subjects. Overrides base_sha/head_sha |
none |
allowed_types |
🏷️ Comma-separated commit types | feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert |
scopes |
🔍 Comma-separated scope allowlist. Empty allows any scope | none |
require_scope |
🔒 Require a scope on every message | false |
description_case |
🔠 Description first-letter case: any, lower or upper |
any |
custom_regex |
🧪 Full POSIX ERE override for the message check | none |
ignore_regex |
⏭️ Subjects and PR titles matching this ERE are skipped. Empty checks all | merge, revert, fixup, squash, amend |
ignore_bots |
🤖 Skip dependabot, renovate, github-actions and *[bot] |
true |
github_actor |
🙋 Actor used for bot detection | the event actor |
skip_labels |
🏷️ Comma-separated labels that skip the whole run | none |
ignore_branches |
🌿 Comma-separated branch globs that skip the whole run | none |
branch |
🌿 Branch name used by ignore_branches |
the PR head branch |
assignees |
👥 Comma-separated assignees | the event assignees |
require_assignees |
🙋 Fail when the PR has no assignee | false |
labels |
🏷️ Comma-separated labels | the event labels |
require_labels |
🏷️ Fail when the PR has no label | false |
is_draft |
📄 Whether the PR is a draft | the event draft flag |
ignore_drafts |
📄 Skip draft PRs | false |
base_sha |
🌱 Base commit. Set with head_sha to check the range |
none |
head_sha |
🌱 Head commit. Set with base_sha to check the range |
none |
max_subject_length |
📏 Max subject characters. 0 disables |
0 |
allow_empty |
🕳️ Pass with skipped=true when there is nothing to lint |
false |
assignees and labels read the event payload. No GitHub token or API call is
made, so the action also works on fork PRs with a read-only token.
| Output | Description |
|---|---|
result |
📊 passed, failed or skipped |
failed |
true when any message or required metadata check failed |
skipped |
true when the whole run was skipped (bot, draft, branch, label or empty input) |
skip_reason |
Why the run was skipped |
valid_count |
Number of messages that passed |
invalid_count |
Number of messages that failed |
skipped_count |
Number of messages skipped by ignore_regex |
checked_count |
Number of messages checked (valid_count + invalid_count) |
invalid_messages |
Newline-separated invalid messages |
- uses: HarryVasanth/fast-commit-linter@v1
id: lint
with:
pr_title: "feat(api): add login"
- if: steps.lint.outputs.failed != 'true'
run: echo "Checked ${{ steps.lint.outputs.valid_count }} messages"A message must look like this:
<type>[optional scope][!]: <description>
Examples that pass:
feat(api): add login endpoint
fix(parser)!: reject empty input
chore: bump dependencies
The rules:
- 🏷️ The type must be in
allowed_types. Types are case-sensitive. - 🔍 A scope is optional and may contain letters, digits,
_,.,/and-. - 💥
!may appear before the colon to mark a breaking change. :needs exactly one space, and the description cannot start or end with whitespace.- 🔠
description_casecan require a lowercase or uppercase first ASCII letter. Non-letters, emoji and non-ASCII letters pass. - 📏
max_subject_lengthis opt-in. Emoji are counted as characters, not bytes. - ⏭️ Merge commits,
Revert "...",fixup!,squash!andamend!are skipped by default, so a merge does not fail the lint. Setignore_regex: ""to check them. - 🔖
ignore_regexalso applies to the PR title. ARevert "..."release PR passes. - 🙈 Set
check_pr_title: "false"to lint commits only.
Nothing to lint is an error. If the PR title is empty and no commits are
collected, the action fails instead of passing silently. Set allow_empty: "true"
to pass with skipped=true instead.
The whole run is skipped when any of these match. The order is draft, branch, bot, then skip label.
- uses: HarryVasanth/fast-commit-linter@v1
with:
skip_labels: "skip-lint,no-commit-check"
ignore_branches: "release/*,dependabot/*"- 📄
ignore_draftswith a draft PR. - 🌿
ignore_brancheswith a branch glob. Matching is case-sensitive and*,?and[...]work. - 🤖
ignore_botswithdependabot,renovate,github-actions, a[bot]suffix orcopilot. - 🏷️
skip_labelswith any label, matched case-insensitively.
A skipped run exits 0 and sets skipped=true, result=skipped and skip_reason.
A compliance check often needs three things: an assignee, a label and a valid commit format. This action does all three in one step, and it checks every commit in the PR range, not just the last one.
name: "📋 Check PR Compliance"
on:
pull_request:
types: [opened, edited, synchronize, reopened, labeled, unlabeled, assigned, unassigned]
jobs:
compliance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: HarryVasanth/fast-commit-linter@v1
with:
allowed_types: "feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert,security"
base_sha: ${{ github.event.pull_request.base.sha }}
head_sha: ${{ github.event.pull_request.head.sha }}
require_assignees: "true"
require_labels: "true"Because it is one action, you get:
- 🧹 Empty commit ranges handled. No phantom invalid commit.
- 💥 The
!breaking-change marker accepted. - 🏷️ Any type or scope list you configure, instead of a hard-coded regex.
- 📊 One step summary with per-message reasons.
- 🤖 Bots and drafts skipped without extra
if:conditions.
To keep a project convention, set allowed_types and, if needed, scopes.
For example, scopes: "api,ui,db" rejects feat(internal): ....
🎯 Fast Commit Linter
🏷️ Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
::error::❌ Invalid PR Title: "Added login" — expected <type>[optional scope][!]: <description>
❌ Invalid PR Title: "Added login"
↳ expected <type>[optional scope][!]: <description>
❌ Validation failed: 1 issue(s)
Format: <type>[optional scope][!]: <description>
Example: feat(api): add authentication endpoint
Example: fix!: drop the legacy schema
Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
🎯 Fast Commit Linter
...
::notice::✅ Skipping lint: automated account (dependabot[bot])
The step passes with result=skipped, skipped=true, and skip_reason explaining why.
🎯 Fast Commit Linter
🏷️ Types: feat, fix, ...
::error::❌ Assignees: assign at least one assignee
❌ Assignees: assign at least one assignee
❌ Validation failed: 1 issue(s)
- uses: HarryVasanth/fast-commit-linter@v1
with:
skip_labels: "skip-lint,no-commit-check"
ignore_branches: "release/*"Label matching is case-insensitive. Branch globs are case-sensitive.
The script reads INPUT_* variables, so it runs outside GitHub Actions. When
GITHUB_OUTPUT is not set, outputs are printed as plain lines.
INPUT_PR_TITLE="feat(api): add login" ./lint-commits.sh
INPUT_COMMIT_MESSAGES=$'fix: crash\nchore: bump deps' ./lint-commits.sh
INPUT_ALLOWED_TYPES="feat,fix,wip" \
INPUT_PR_TITLE="wip(ui): draft" \
./lint-commits.sh
INPUT_DESCRIPTION_CASE=lower \
INPUT_IGNORE_BRANCHES="release/*" \
INPUT_BRANCH="release/2.0" \
./lint-commits.shRun the self-check (86 cases, bash 3.2 compatible):
./lint-commits.test.sh- 📝
commit_messagesis one subject per line. Bodies and footers are not parsed. Setbase_sha/head_shato let git collect the subjects. A blank list falls back to the range. - 🌱 Commit collection needs
fetch-depth: 0(or enough history) for the base commit. A missing SHA fails with a clear message. - 🔎 GitHub shows at most 10
::error::annotations per step. Every invalid message is still printed to the log and the summary. - 🧾 The step summary lists up to 50 invalid and 50 skipped messages. The log lists all of them.
- 🧪
custom_regexreplaces the format check only.max_subject_lengthanddescription_casestill apply.scopesandrequire_scopeare ignored with a warning. - 🔠
description_casecompares the first character after:. With acustom_regexthat has no:delimiter, the case check is skipped. - 🌿
ignore_branchesmatches thebranchinput, not the fullrefs/heads/...name. - ⏭️
skipped_countcounts every message skipped byignore_regex, including the PR title.
- No runtime downloads. The action runs the script from its own repository.
- No token. Labels and assignees come from the event payload.
- Untrusted text stays text. Titles and commit messages are never evaluated. Workflow commands are escaped, and Markdown table cells have pipes and backticks removed.
- Pin a version. Reference a release tag rather than a branch, and bump it deliberately:
- uses: HarryVasanth/fast-commit-linter@v1