Lint your linting.

Governance Pipeline Auditor scans a repo’s Spectral API-governance CI setup and scores it against an 8-point maturity rubric — then hands back a prioritized punch-list of concrete fixes. It’s the sequel to Spectral Reporter: that reports on your API, this reports on your pipeline. The rubric comes straight from the API Evangelist paper “The State of Spectral in API Pipelines,” a census of 1,005 real public pipelines.

Try the live demo ↓ Install & usage

npx @api-common/governance-pipeline-auditor . --min-score 5

8-point rubric

Gates the PR · custom ruleset · owned home · pinned tooling · security layer · real gate · path-filtered · machine-readable report.

Prioritized punch-list

Every failed signal becomes a concrete fix, ordered by governance impact, each with a one-line why and a docs link.

Gate on the score

A composite GitHub Action writes the score to your job summary and fails the build under --min-score.

Anti-pattern flags

Calls out the specific smells from the paper — default ruleset, @latest, lint-after-merge, toothless continue-on-error.

Live demo

Paste your .github/workflows/*.yml that runs Spectral (and, optionally, your .spectral.yaml ruleset), then score it — all in your browser, with the exact scorer the CLI uses.

Workflow YAML

Ruleset (optional)

Audit preview

The 8-point rubric

One point per signal. It deliberately measures only the mechanical surface a workflow file exposes — the automatable quarter of governance. It says nothing about whether a human wrote the rules on purpose.

Signal	Question it answers
Gates the PR	Does governance fire before the merge, not after?
Custom ruleset	Are the rules the organization’s, not the tool’s defaults?
Owned ruleset home	Do the rules live in a dedicated dir or a shared/remote source?
Pinned tooling	Is the enforcing tool pinned to a chosen version (SHA)?
Security layer	Are OWASP/security rules present, not just style?
Real gate	Does it fail the build on error rather than only annotate?
Path-filtered	Does it run only when the spec/ruleset changes?
Machine-readable report	Does it emit SARIF / a readable report / PR comment?

Install & usage

Run it now (no install)

# Audit the current repo and print the score + punch-list
npx @api-common/governance-pipeline-auditor .

# Short alias, JSON output, and a gate
npx @api-common/governance-pipeline-auditor . --json
npx @api-common/governance-pipeline-auditor . --min-score 5

# Write a self-contained HTML report
npx @api-common/governance-pipeline-auditor . --html governance-audit.html

Install as a dev dependency

npm install --save-dev @api-common/governance-pipeline-auditor

Flags

--json — print the full audit as JSON
--html <file> — write a self-contained HTML report
--summary <file> — append a Markdown summary (for CI / $GITHUB_STEP_SUMMARY)
--min-score <N> — exit non-zero if the score is below N (gate a pipeline)

In GitHub Actions

- uses: api-commons/governance-pipeline-auditor@v1
  with:
    path: .
    min-score: 5      # fail the job below 5/8
    html: governance-audit.html
- uses: actions/upload-artifact@v4
  with:
    name: governance-audit
    path: governance-audit.html

The scorer is a pure, dependency-free function shared verbatim between the CLI, the Action, and this page — so the score you see here is byte-for-byte what CI produces. Free and open under the Apache-2.0 license. When you want experts in the loop, .