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.
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.
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=errorThe 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.
| Tool | How it gates the PR | Distinguishing feature |
|---|---|---|
| Spectral | Fails the CI job on error-level rule violations; red check blocks merge | The most widely adopted; also the engine inside Stoplight's hosted platform |
| Redocly CLI | Same pattern, `redocly lint ... --format=github-actions` | Bundles linting with spec bundling and documentation preview in one tool |
| vacuum | Fails the build on errors or a quality-score threshold; publishes a JUnit report | Open source; richer PR-level annotation of exactly which rule failed |
| Fortellis Spec Lint Action | Gates the push on detected errors for OAS 2.0 specs | Built 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 checked | The OpenAPI spec: naming, required fields, structure, style | policies.json: allow/deny/approval rules for an agent's calls at runtime |
| When the problem would otherwise show up | When a human or agent tries to use a badly-designed endpoint | When an agent's actual call violates a rule nobody wrote a guard for |
| What blocks the PR | A red CI check on the spec file itself | A 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
- What CI runs when agent integrations change in git: https://www.swytchcode.com/content/ci-for-agent-integrations
- Policy-as-Code for AI Agents: allow, deny, and approve rules in git: https://www.swytchcode.com/blogs/policy-as-code-for-ai-agents
- API Governance Tools for AI Agents: https://www.swytchcode.com/content/api-governance-tools-ai-agents
- How to set up policy guardrails for AI agents: https://www.swytchcode.com/blogs/how-to-set-up-policy-guardrails-for-ai-agents-with-swytchcode
- Swytchcode pricing: https://www.swytchcode.com/pricing
More content
API Governance Tools With a Free Tier: What Small Teams Can Actually Use
Most API governance comparisons assume an enterprise budget. Here's what's genuinely free with no catch, what's gated behind a paid plan, and the realistic free stack a small team can actually run.
API Spend Caps for AI Agents: Capping Cost Before the Invoice Does
Most teams find out an agent overspent on a metered API when the invoice arrives. An argument-level policy that caps the metric a provider actually bills on, checked before the call goes out, catches it in the moment instead.
What APIs Do B2B SaaS Companies Use for Customer Communication?
Five categories of API, email, in-app messaging, SMS, push, scheduling, each with its own failure mode when an AI agent calls it. A landscape view of the risks and the policy mechanisms that address each one.
