For two years I have been saying in print that “just turn on Spectral” is a seduction and a trap — that flipping on a linter’s default ruleset in your pipeline and waiting to wake up governed is not governance, it is the visible five percent of it wearing governance’s clothes. It is one thing to assert that from a keyboard. So I stopped asserting and went and looked. I pulled every public GitHub repository I could find that runs Spectral inside a .github/workflows/ pipeline, read the actual workflow files, threw out the name-collisions — there is an unrelated security product called “Spectral,” and astronomy and blockchain projects that share the word — and characterized how each of the survivors really uses it. After filtering, I had 1,005 real pipelines. This is not a survey of what vendors recommend or what conference talks describe. It is a census of what teams actually shipped.
The headline is the one I was afraid I would find. Sixty-three percent of them — 633 pipelines — run Spectral with its default or implicit ruleset and no rules of their own. They are not governing their APIs against a definition of what a good API means at their organization. They are running a linter’s factory settings against their specs and calling the green check governance. The most common way to use a governance tool, it turns out, is to not govern with it.
Everything else in the data radiates out from that one fact. The community’s own CLI is used almost three-to-one over the official spectral-action GitHub Action — most teams are assembling the pipeline out of whatever fragment they found first, not walking the paved road. Of the teams that do use the Action, nearly half pin it to a floating @latest that can change behavior under them between one Tuesday and the next, with no commit in their repo and no line in their changelog; exactly fourteen out of a thousand pin to a specific commit on purpose. A third of the pipelines don’t fire on the pull request at all — they run after the merge, which is governance reporting on a decision instead of informing it. Thirteen percent run the linter with continue-on-error set, so it produces findings and never fails a build regardless of what it finds — decorative governance, there so the pipeline can say it lints. Security rules show up in fourteen percent. SARIF, the format that would surface findings in GitHub’s own security tab, in barely three.
I scored every pipeline against an eight-point maturity rubric — does it gate the PR, is the ruleset custom, is the tooling pinned, is there a security layer, does it emit a report a machine can read, and so on. The scores clustered at two and three. The ceiling was six. Two repositories out of a thousand reached it. Nobody scored seven or eight.
Here is the part I want to be careful about, because it is the whole argument compressed into a statistic. That rubric measures only the mechanical surface a workflow file exposes. It cannot see whether a human wrote those rules on purpose, whether anyone owns them, whether a developer who trips one understands why. Governance is roughly three-quarters people work and one-quarter machinery, and a census of pipeline files can only ever see the machinery. So the finding is not “these pipelines are 6/8 governed.” The finding is that even the mechanical quarter — the part that is supposed to be the easy, automatable part — is thin almost everywhere, and the three-quarters that actually decides whether governance works is, by definition, not in the file at all. If the easy part looks like this, the conversations about the hard part have mostly not happened.
Why does the default-ruleset majority matter so much? Because a ruleset you did not write is a ruleset nobody at your organization had to think through. The default ruleset is not a standard — it is a config file that ships with the software, a hodgepodge of atomic checks that accreted in an open-source project without a naming convention, without categories, with no implication anywhere that the authors even recommend you run all of them. And turning a few hundred of them on against a mature API does a specific kind of damage: you don’t get a clean bill of health, you get a wall of red, a hundred and forty findings on an API that has been serving production traffic happily for three years. The team’s first encounter with “governance” teaches them, in one afternoon, permanently, that the program is noise to route around. You manufacture the governance-skeptical cohort on purpose, at the exact moment you can least afford to.
It was not all bleak. There is a thin band — you can almost count them — doing governance as something owned. The clearest signal in the entire dataset is a shared, remotely-referenced ruleset, and it appears in eight of the 1,005 pipelines. The standout is a cluster of Italian public-sector repositories that pull their ruleset, at pipeline time, from a national API-guidelines project maintained centrally by the country’s digital-government team. The rules live in one governed place, versioned, owned, carrying the weight of an actual policy decision made once and applied across many teams. That is the difference between governance as an owned, provenanced artifact and governance as a config file each team pasted in and forgot. Elsewhere in the corpus you find the other blueprint parts scattered like components in a scrapyard: a database company that pins its Action by commit and path-filters its triggers; a geospatial project that runs a dedicated OWASP security job and writes a readable report; a commerce platform that lints only the files that changed and posts the findings back as a PR comment. None of these teams did all of it. Each did one part deliberately. The blueprint nobody in the corpus has fully assembled is sitting right there, in pieces, already shipping.
I wrote the whole thing up as a paper — The State of Spectral in API Pipelines — which walks the data and turns it into that blueprint: why the defaults are theater, why floating tooling is ungoverned governance, how to gate consistently but sparingly, why even a perfect mechanical score measures only a quarter of the work, and the rare pattern of governance as a shared, owned, questionable artifact. It closes on the reframe that matters most as agents become the least forgiving consumers of your APIs: everything the default-ruleset majority has been getting away with becomes a hard failure the moment the consumer is a machine that cannot read between the lines of your spec.
And because a linter by its nature only ever tells people what is wrong — it is a machine for surfacing deficits — I built a free companion tool for the paper. Spectral will happily emit its findings as JSON; what it will not do is turn that JSON into something a human will actually read and a team will rally around, the way newman-reporter-htmlextra did for Postman runs years ago. So reporter.apicommons.org does that for governance: drop your spectral lint JSON in, get a single self-contained HTML report — severity summary, grouped by rule and file, top offenders, searchable, framed toward progress rather than just deficit. You wire it in after the lint step and attach the HTML as a build artifact, and suddenly even the thirteen percent running toothless advisory-only linting have something better than nothing, and everyone else has a report a non-engineer can read. It joins the free governance validator at validator.apicommons.org.
The teams in the top band of this corpus are not ahead because they run more rules. They are ahead because someone decided, on purpose, what their APIs should be, wrote it down where it could be owned and questioned, and wired it into the pipeline as a gate that informs rather than a wall that punishes. That is the whole blueprint. A thousand pipelines show how rare it still is — and that not one piece of it is actually hard, because every part is already shipping somewhere in the data. It is waiting to be assembled, on purpose, by teams ready to stop mistaking the green check for the work.
