0.3.0: GitHub Action and branch audit

Explain required checks on every pull request, and audit a branch before a pull request gets stuck.

GitHub Action. Add .github/workflows/explain-required-checks.yml:

name: Explain required checks
on:
  pull_request:
concurrency:
  group: explain-required-checks-${{ github.event.pull_request.number }}
  cancel-in-progress: true
permissions:
  contents: read
  actions: read
  checks: read
  statuses: read
  pull-requests: write
jobs:
  explain:
    runs-on: ubuntu-latest
    steps:
      - uses: builtbysharath/gh-pr-check-explainer@v0

When a required check can't report because of configuration (a paths or branches filter, no pull request event, a renamed job, the wrong reporting app, an ineligible event, or a fork's workflows awaiting approval), the action posts one comment with the check, the cause and a fix, and keeps it up to date. Every run writes the full report to the job summary. Outputs: verdict and stuck-checks; fail-on-stuck: true fails the job.

Branch audit. No pull request needed:

gh pr-check-explainer --audit OWNER/REPO [--branch NAME]

It flags required checks that some pull requests would wait for: filtered or push-only workflows, workflows with no pull request event, names no workflow reports, names several workflows report, and merge queues the reporting workflow doesn't run for. Exit code 1 means a risk.

Also in this release

• Matrix job names are expanded the way GitHub names their check runs, so required checks like build (macos-latest) are traced to their workflow.
• Classic branch protection is diagnosed without admin access, from the branch summary.
• JSON reports give each required check a cause when configuration explains a missing result.

Install or update the CLI extension with gh extension install builtbysharath/gh-pr-check-explainer (add --pin v0.3.0 to stay on this release), or run it once without installing:

npm exec --yes --package=https://github.com/builtbysharath/gh-pr-check-explainer/releases/download/v0.3.0/gh-pr-check-explainer-0.3.0.tgz -- gh-pr-check-explainer https://github.com/OWNER/REPO/pull/NUMBER

Requires Node 22+. The CLI and the audit are read-only; the action's only write is its one pull request comment. Full list in the CHANGELOG.