Your Spectral pipeline scores 5/8 — a short path to the top band

[kinlane]

Your Spectral pipeline scores 5/8 — a short path to the top band

Hi 👋 — I run API Evangelist, and I recently published a field study of 1,005 real public GitHub pipelines that run Spectral to govern their APIs (The State of Spectral in API Pipelines). Your pipeline came up as already ahead of most of the field, so I ran it through the free, open-source auditor that came out of that research and wanted to share the result — plus a short, concrete path to the top band.

This is a friendly drive-by from someone who studies API governance for a living, not a bug report. Take or leave any of it.

The score: 5 / 8 “Developing”

For context: 63% of the 1,005 pipelines in the census run Spectral's defaults with no real governance behind them. You're past that. A handful of deliberate additions would take this to the top band.

You can reproduce it yourself in one command (no install):

npx @api-common/governance-pipeline-auditor .

What you're already doing right ✅

Signal	What I saw
Gates the PR	governance runs before merge, not after — pull_request:
Custom ruleset	the rules are a decision you made, not the tool's defaults — if ! spectral lint "$file" -e utf8 -D -f json -o "$output_file" -r spe
Owned ruleset home	the ruleset has a governed, versioned home — run: wget https://github.com/italia/api-oas-checker-rules/releases/lat
Real gate	the step actually fails the build — it's a gate, not a decoration — no continue-on-error:true on the governance step
Path-filtered	it runs only when specs/rulesets change — paths:

The gaps to 8/8

1. Pin the enforcing tool.

Pin stoplightio/spectral-action to a full 40-char commit SHA, or the CLI/ruleset to exact versions (@stoplight/spectral-cli@6.16.1). A governance tool on @latest can change what passes between two Tuesdays with no commit and no changelog.

_{why this matters →}

2. Add a security layer.

Extend an OWASP API Top-10 ruleset — @stoplight/spectral-owasp-ruleset or the Apache-2.0 @api-common/spectral-owasp-ruleset (22 grounded rules). Style rules miss the class of problems that actually hurt consumers.

_{why this matters →}

3. Emit a report a human will read.

Upload SARIF to the Security tab, post a PR comment, or pipe findings through @api-common/spectral-reporter for a single self-contained HTML report:

spectral lint -f json <spec> | npx @api-common/spectral-reporter -o governance-report.html

_{why this matters →}

Tooling (all free, open, Apache-2.0)

Everything above comes out of the API Commons governance tool family, built from this research:

• governance-pipeline-auditor — "lint your linting"; the 8-point score above as a CLI + composite Action. Add --min-score 6 to CI to prevent regressions.
• spectral-reporter — Spectral JSON → self-contained HTML report.
• spectral-owasp-ruleset — OWASP API Top-10 rules, Spectral default functions only.
• governance-pipeline — a forkable reference blueprint wiring all of the above together.

Suggested next steps

1. Emit a report a human will read (→ 6/8)
2. Pin the enforcing tool (→ 7/8)
3. Add a security layer (→ 8/8 — you'd be the first in the census)
4. Add governance-pipeline-auditor . --min-score 6 as a CI step so the score can't slip back.

Happy to open a PR for any of these if it'd help — just say the word. Nice work on this pipeline. 🙏

— Kin Lane, API Evangelist · tools by API Commons