Skip to content

Check PR Requirements

Actions

About

Validates pull request properties against configurable requirements
v0.3.0
Latest
Star (0)

Tags

 (1)

Check PR Requirements

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.

Available Checks

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

Usage

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"

Minimal Configuration

Only check what you need:

- uses: AbsaOSS/check-pr-requirements@v0.1.0
  with:
    check-title: "true"
    check-description: "false"
    check-issue-reference: "false"

Inputs

PR Data

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.

Check Configuration

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.

Outputs

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

Bypass trust model

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).

PR comment and concurrent runs

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

Adding a New Check

  1. Create checks/my_check.sh — sources lib.sh, reads INPUT_* env vars, prints pass, fail: reason (exit 1) or, via config_error, config error: reason for invalid configuration (exit 2; reported as an error even when listed in warn-checks); exits 0 on pass
  2. Add entry to REGISTRY array and a "How to fix" tip to remediation_for in check.sh
  3. Add inputs to action.yml (toggle + config) and their env mapping in the composite step
  4. Put non-trivial config defaults in checks/defaults.sh (tests/test_defaults.sh checks they match action.yml)
  5. Create tests/test_my_check.sh — tests/run_tests.sh picks up every tests/test_*.sh automatically

License

Apache License 2.0 — see LICENSE.

Check PR Requirements is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.

About

Validates pull request properties against configurable requirements
v0.3.0
Latest

Tags

 (1)

Check PR Requirements is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.