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.

0.2.0: GitHub CLI extension

Install as a GitHub CLI extension and paste a PR link:

gh extension install builtbysharath/gh-pr-check-explainer
gh pr-check-explainer https://github.com/OWNER/REPO/pull/NUMBER

• The extension runs a committed single-file bundle that CI rebuilds and compares with the source. Add --pin v0.2.0 to stay on this release.
• Pass a standard https://github.com/OWNER/REPO/pull/NUMBER URL instead of --repo and --pr.
• The example report links back to the overview and to trying the tool, shows fictional evidence without clickable links, and has Copy buttons for its Markdown and the install command.

Prefer not to install anything:

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

Requires Node 22+ and an authenticated GitHub CLI. Read-only: it never reruns workflows, posts comments or changes settings. Tested on macOS and Linux.

0.1.0: initial prerelease

Initial experimental prerelease of PR Check Explainer: read-only required-check diagnosis with policy, commit/App identity, supported workflow evidence and strict branch freshness. Export HTML, JSON or Markdown; use captured snapshots for repeatable analysis.

Requires Node 22+ and existing GitHub CLI authentication for live GitHub.com PRs. The tool does not execute workflows or change repository policy. Complex/matrix/reusable workflow cases and incomplete policy access remain uncertain. This verdict is scoped and is not overall merge permission.

Validation: 45 automated tests; all four CI jobs passed on Linux/macOS with Node 22/24. Public captured benchmark cases and known limitations are documented in the repository.

Assets include a source archive, an installable npm-format tarball, a source manifest and SHA-256 checksums. Install the downloaded .tgz locally with npm; this package has not been published to the npm registry.

CI: https://github.com/73sharath73/gh-pr-check-explainer/actions/runs/37958226566
Source commit: 655d7d2f78937ab329bb081b7b80895fe32ccf81