Content

API Governance Tools That Block a Pull Request When a Policy Check Fails

Spectral, Redocly CLI, and vacuum all fail a PR's CI check when an OpenAPI spec breaks a governance rule. How the gate is actually wired up, and why it's a different layer from Swytchcode's own runtime policy checks.

EngineeringNov 18, 2026

Key takeaways

  • -This is a design-time gate on the OpenAPI spec itself, a different artifact and failure mode from Swytchcode's own CI validation of policies.json, which governs runtime agent calls
  • -Spectral is the engine behind most of this pattern; its CLI fails CI on error-level rule violations while letting warnings print without blocking the merge
  • -Teams assemble this pipeline by calling the Spectral CLI directly almost three-to-one over the official spectral-action GitHub Action, which matters when troubleshooting a nonstandard setup
  • -Redocly CLI and vacuum implement the same PR-blocking pattern with different engines; vacuum adds richer per-rule PR annotation via a published JUnit report
  • -A spec-lint gate and Swytchcode's runtime policy layer catch different mistakes made by different people at different points in the process; a mature setup has reasons to run both

This is a different question from the one our CI and policy-as-code posts answer. Those cover validating Swytchcode's own policies.json, the file that governs what an AI agent is allowed to call at runtime, on every commit. This post is about a separate artifact entirely: the OpenAPI spec itself, and the tools that fail a pull request's CI check when that spec violates a design-time governance rule, before the API is ever built or exposed to an agent.

What this covers: the tools that actually implement a PR-blocking governance gate for an API spec, how the gate itself is wired into GitHub Actions, and where this kind of spec-level governance sits relative to Swytchcode's own runtime policy layer, because a mature setup has reasons to run both.

Spectral: the tool most of this category is actually built on

Spectral, Stoplight's open-source OpenAPI and AsyncAPI linter, is the engine behind most of this pattern. By default, the CLI only exits with a non-zero code when it finds an error-level rule violation, warnings print but don't fail the run, which matters while you're cleaning up a legacy spec and don't want a thousand warnings blocking every merge on day one.

.github/workflows/lint.yml
name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error

The job fails when the spec breaks an error-level rule, the pull request shows a red check, and the merge is blocked until someone fixes it. One piece of real-world data worth knowing: a 2026 survey found teams actually assembling this pipeline by calling the Spectral CLI directly almost three-to-one over using the official pre-built `spectral-action`, most teams wire it up from whatever fragment they found first rather than the maintained path, which matters if you're troubleshooting a setup that doesn't match the official docs.

Redocly CLI and vacuum: the same pattern, different engines

Redocly's CLI bundles linting with spec bundling and a docs preview, and wires into the same PR-gate pattern with its own command and a GitHub-Actions-formatted output. Vacuum, an open-source alternative, goes a step further by publishing lint results as a JUnit report through a GitHub Check, so a pull request shows not just pass/fail but an annotated breakdown of exactly which rule failed where.

ToolHow it gates the PRDistinguishing feature
SpectralFails the CI job on error-level rule violations; red check blocks mergeThe most widely adopted; also the engine inside Stoplight's hosted platform
Redocly CLISame pattern, `redocly lint ... --format=github-actions`Bundles linting with spec bundling and documentation preview in one tool
vacuumFails the build on errors or a quality-score threshold; publishes a JUnit reportOpen source; richer PR-level annotation of exactly which rule failed
Fortellis Spec Lint ActionGates the push on detected errors for OAS 2.0 specsBuilt for a specific industry ecosystem (auto finance APIs), not general-purpose

Where this actually differs from Swytchcode's own CI story

Swytchcode's own CI guidance covers validating policies.json, the runtime rules that decide whether an agent's call is allowed, denied, or held for approval, on every commit, and dry-running each method a diff adds before anything live happens in the pipeline. That's a genuinely different artifact and a genuinely different failure mode from what Spectral, Redocly, or vacuum check.

Spec-lint gate (this post)Swytchcode's own CI validation
What's being checkedThe OpenAPI spec: naming, required fields, structure, stylepolicies.json: allow/deny/approval rules for an agent's calls at runtime
When the problem would otherwise show upWhen a human or agent tries to use a badly-designed endpointWhen an agent's actual call violates a rule nobody wrote a guard for
What blocks the PRA red CI check on the spec file itselfA failed dry-run or a policy-file validation error

A well-designed, clean OpenAPI spec says nothing about whether the agent calling it is allowed to issue a $50,000 refund. Conversely, an airtight policy file doesn't fix an API whose spec is so inconsistent that nobody, human or agent, can reliably predict what a field means. Teams that have both gates running get a different kind of coverage than teams with either one alone, because the two gates are watching for different kinds of mistakes made by different people at different points in the process.

FAQ

Does a Spectral PR gate protect against an AI agent making a bad call at runtime?

No. A spec-lint gate only runs when the spec file itself changes, and it checks the spec's shape and style, not what happens once an agent starts calling a live endpoint built from that spec. Runtime protection against a bad call is a separate layer, the kind Swytchcode's own policy evaluation provides, enforced on every call, not on every spec change.

Can a developer bypass one of these PR gates with --no-verify?

Not the CI version. A local pre-commit hook can be skipped with `--no-verify`, but a GitHub Actions check on the pull request itself runs on GitHub's infrastructure, not the developer's machine, so there's no local flag that skips it. That's exactly why the guidance in this space treats the CI-based gate, not a local hook, as the one that actually matters.

Which of these tools should a team pick if they're starting from nothing?

Spectral is the most widely adopted and has the most available rulesets and documentation to start from, which usually makes it the lower-friction starting point. Vacuum is worth a look specifically for its richer PR annotations if detailed per-rule feedback in the pull request itself matters to your team.

Does this replace a human review of the API design?

No. A lint gate catches objective, rule-based violations, a missing required field, inconsistent casing, a missing security scheme, not judgment calls about whether the API's design is actually good for its intended use. The gate is a floor, not a substitute for someone with API design experience reviewing the change.

Swytchcode resources

More content