Required Checks Auditor

Catch GitHub pull-request checks that run but are not required by your branch rules.

Installation

Run the following command from the repository you want to protect. It finds your PR workflows, asks which ones to watch, then writes .github/workflows/required-checks-auditor.yml.

npx -y required-checks-auditor@latest

name: Audit Required PR Checks

on:
  pull_request:
    branches: [main]
    types: [opened, ready_for_review, reopened, synchronize]
  branch_protection_rule:
    types: [created, edited, deleted]

permissions:
  contents: read
  checks: read
  statuses: read

jobs:
  required-checks-auditor:
    name: Required checks auditor
    runs-on: ubuntu-latest
    steps:
      - id: audit
        uses: biw/[email protected]
        with:
          target-branch: main
          wait-seconds: 10
          excluded-workflow-paths: |
            .github/workflows/release-build.yml
            .github/workflows/release-publish.yml
      - name: Upload starter ruleset
        if: ${{ failure() && steps.audit.outputs['ruleset-artifact-path'] != '' }}
        uses: actions/upload-artifact@v4
        with:
          name: required-checks-ruleset
          path: ${{ steps.audit.outputs['ruleset-artifact-path'] }}
          if-no-files-found: error

Usage

After the workflow has run once, add Required checks auditor to the required status checks in each branch rule or ruleset that protects the target branch. The first run fails until you do—this is expected, and proves that the auditor itself cannot be left optional.

Keep the three permissions from the example so the auditor can read workflows, external checks, and the effective branch rules.

Options

• wait-seconds: seconds to wait before auditing; defaults to 10. Set 0 to run immediately.
• target-branch: protected branch whose active rules are audited. It defaults to the pull request's base branch; set it explicitly when the workflow can run on stacked pull requests.
• excluded-workflow-paths: workflow files to leave out of automatic discovery when you intentionally do not want their checks audited.
• ignored-checks: specific check names to leave out intentionally.

Generated workflow

• Setup pins target-branch to the branch you choose, so stacked pull requests audit the protected branch rather than an intermediate branch.
• Rerunning setup preserves existing excluded-workflow-paths and ignored-checks values.

What the audit discovers

• GitHub Actions checks in eligible workflows, plus external checks observed on the pull request.
• Job names that interpolate literal strategy.matrix values are expanded into their concrete check names. Expressions that depend on any other context still need a static job name or a workflow exclusion.
• Workflows that can run only after a pull request closes or through manual dispatch are ignored.

If no active ruleset applies to the target branch and checks are missing, the failed run includes a required-checks-ruleset artifact. Download it and import it in Settings → Rules → Rulesets. If a ruleset already applies, the action only reports the missing checks so you can update that existing policy.

License

MIT