A configurable GitHub Action that validates pull request properties against a set of requirements. Each check can be independently enabled/disabled, making it easy to enforce only the rules that matter for your project.
| Check | Default | Description |
|---|---|---|
check-title |
true |
PR title matches an allowed format: Conventional Commits, issue-number prefix (#123: Title), or custom regex |
check-description |
true |
PR body meets minimum length and contains required sections |
check-issue-reference |
true |
PR references a GitHub issue (#123, org/repo#123, Fixes #123, issue URL) or Azure Boards work item (AB#12345) |
check-release-notes |
false |
PR body contains release notes section (uses AbsaOSS/release-notes-presence-check); its result is part of the summary table and counts |
check-branch-name |
false |
Source branch follows naming convention |
check-pr-size |
false |
PR does not exceed maximum file change count and, optionally, changed line count |
check-label |
false |
PR has required labels |
check-target-branch |
false |
PR targets an allowed branch |
name: Check PR Requirements
on:
pull_request:
types: [opened, synchronize, reopened, edited, labeled, unlabeled]
permissions:
contents: read
pull-requests: write # PR comment on failure (comment-on-failure)
jobs:
check-pr:
runs-on: ubuntu-latest
steps:
- name: Check PR requirements
uses: AbsaOSS/check-pr-requirements@v0.1.0
with:
check-title: "true"
check-description: "true"
check-issue-reference: "true"
check-release-notes: "true"Only check what you need:
- uses: AbsaOSS/check-pr-requirements@v0.1.0
with:
check-title: "true"
check-description: "false"
check-issue-reference: "false"PR data is read from the pull_request event by default, so these inputs are only needed to override it (e.g. on other event types).
| Input | Default | Description |
|---|---|---|
pr-title |
github.event.pull_request.title |
Pull request title |
pr-body |
github.event.pull_request.body |
Pull request body/description |
pr-branch |
github.event.pull_request.head.ref |
Source branch name |
pr-author |
github.event.pull_request.user.login |
PR author login (used with skip-actors) |
pr-number |
github.event.pull_request.number |
Pull request number |
target-branch |
github.event.pull_request.base.ref |
Target branch name |
files-changed |
github.event.pull_request.changed_files |
Number of files changed |
additions |
github.event.pull_request.additions |
Lines added (used with max-lines-changed) |
deletions |
github.event.pull_request.deletions |
Lines deleted (used with max-lines-changed) |
labels |
PR label names joined with , |
Comma-separated list of PR labels |
github-token |
github.token |
GitHub token (used by the release notes check and comment-on-failure) |
A check whose PR data is empty fails with a message naming the missing input.
| Input | Default | Description |
|---|---|---|
title-formats |
conventional |
Comma-separated allowed title formats, pass if any matches: conventional, issue-number (#123: Title or 123 - Title), custom |
title-types |
feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert |
Allowed conventional commit types (conventional format) |
title-scopes |
(empty = any) | Allowed scopes (conventional format), e.g. api,ui,auth |
title-pattern |
(empty) | Regex the title must match (custom format), e.g. ^\[[A-Z]+-[0-9]+\] .+ (matches [PROJ-123] Title) |
title-require-scope |
false |
Require a scope in conventional titles, e.g. feat(api): ... |
title-max-length |
(empty = unlimited) | Maximum title length, applied to every format (e.g. 72 for squash-merge subjects) |
description-min-length |
20 |
Minimum description character count |
description-required-sections |
(empty = none) | Comma-separated headings that must appear in the PR body, e.g. ## Overview,## Release Notes |
description-ignore-comments |
false |
Ignore <!-- --> comments (PR template hints) for the length and section checks, so an untouched template fails |
description-require-section-content |
false |
Each required section must be a heading line (matched ignoring case) with text under it before the next heading of the same or higher level; comments do not count |
issue-reference-require-keyword |
false |
Only keyword references in the PR body count (Fixes #123, Closes AB#12345), matching what GitHub links; bare #123 / AB#123 / URLs and keywords in the title are rejected |
branch-pattern |
^(feature|bugfix|hotfix|release|support|chore|docs|ci|dependabot)/[a-zA-Z0-9._/-]+$ |
Full branch name regex override |
branch-require-ticket |
false |
Require a ticket after the branch prefix (feature/123-user-login) |
branch-ticket-pattern |
^[^/]+/[0-9]+- |
Regex the branch must match when branch-require-ticket is true. Override for non-numeric schemes, e.g. ^[^/]+/[A-Z]+-[0-9]+- for feature/PROJ-123-... |
max-files-changed |
50 |
Maximum files changed |
max-lines-changed |
(empty = no limit) | Maximum changed lines (additions + deletions); the size check fails if either limit is exceeded |
required-labels |
(empty = any label) | Required label names, matched ignoring case, e.g. bug,enhancement |
allowed-target-branches |
main,master |
Allowed target branches; glob patterns supported (main,support/*) |
annotations |
true |
Emit an error (or warning) annotation per failed check, shown on the PR's Checks tab |
comment-on-failure |
true |
Keep one PR comment with the summary and "How to fix" while checks fail; delete it once they pass or are bypassed by skip-actors/skip-labels. Requires pull-requests: write and the gh CLI (preinstalled on GitHub-hosted runners); on fork PRs the pull_request token is read-only, so the comment is skipped. A failure to comment never fails the job; set false to opt out |
skip-actors |
(empty = no bypass) | Comma-separated PR-author logins (ignoring case) that bypass all checks (needs pr-author wired), e.g. dependabot[bot] |
skip-labels |
(empty = no bypass) | Comma-separated PR labels (ignoring case) that bypass all checks (needs labels wired), e.g. skip-checks,automated |
warn-checks |
(empty = all blocking) | Comma-separated check ids whose failed results are warnings, e.g. pr-size,label |
release-notes-tag |
## [Rr]elease [Nn]otes |
Release notes section header pattern |
release-notes-skip-labels |
no RN |
Labels that skip release notes check |
release-notes-skip-placeholders |
TBD |
Placeholders indicating missing notes |
Boolean inputs accept true/false in any letter case. Invalid configuration (a non-boolean toggle, a non-numeric limit, an invalid regex, an unknown title format) is reported as ⚠️ Error with the offending input named, and fails the job, so it is not mistaken for a problem with the PR.
| Output | Description |
|---|---|
result |
pass or fail |
pass-count |
Number of checks passed |
fail-count |
Number of checks failed (excludes action configuration errors such as unknown warn-checks ids, which still set result to fail) |
warn-count |
Number of checks reported as warnings |
total-count |
Total checks executed |
failed-checks |
Comma-separated ids of failed checks, e.g. title,pr-size |
summary |
Markdown summary (the same text as the job summary) |
skipped |
true when all checks were bypassed by skip-actors or skip-labels |
skip-reason |
Why the checks were bypassed, e.g. author dependabot[bot] matched skip-actors |
skip-labels lets anyone who can label PRs (triage access or higher) bypass every check. Use a dedicated label that is not applied by automation, and rely on branch protection reviews for PRs that carry it. skip-actors matches the PR author login, so wire pr-author to github.event.pull_request.user.login, not github.actor (the user who triggered the run).
With comment-on-failure, the action looks up its comment by a hidden marker and then creates or updates it. Two runs for the same PR (e.g. a push right after a label change) can both miss the lookup and post a comment each; the action then keeps the oldest marker comment and deletes the others. To avoid the overlap altogether, let only the latest run per PR proceed:
concurrency:
group: check-pr-requirements-${{ github.event.pull_request.number }}
cancel-in-progress: true- Create
checks/my_check.sh— sourceslib.sh, readsINPUT_*env vars, printspass,fail: reason(exit 1) or, viaconfig_error,config error: reasonfor invalid configuration (exit 2; reported as an error even when listed inwarn-checks); exits 0 on pass - Add entry to
REGISTRYarray and a "How to fix" tip toremediation_forincheck.sh - Add inputs to
action.yml(toggle + config) and their env mapping in the composite step - Put non-trivial config defaults in
checks/defaults.sh(tests/test_defaults.shchecks they matchaction.yml) - Create
tests/test_my_check.sh—tests/run_tests.shpicks up everytests/test_*.shautomatically
Apache License 2.0 — see LICENSE.