How-to 7 min read • Updated Jan 2026

CI guardrails for OpenAPI changes with GitHub Actions

The fastest way to stop spec drift is to add a contract check to every pull request. This guide shows the flow and a starter workflow you can adapt.

Step 1: keep the spec in the repo

The OpenAPI document must live in the same repo as the service so changes stay visible. Store it in a predictable path, like /openapi.yaml.

The goal is simple: diff the spec against the code and flag breaking changes before merge. Run this on every PR to keep the review signal tight.

Your reviewers should see a short summary with severity and affected endpoints. That keeps the discussion focused on risky diffs.

This workflow calls the TrueSpec reports API and writes a summary into the PR checks tab.

name: api-contract

on: [pull_request]

jobs:

  drift:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

        with:

          fetch-depth: 0

      - uses: actions/setup-node@v4

        with:

          node-version: 20

      - uses: alessiobianchini/TrueSpecAction@v0

        with:

          spec-path: openapi.yaml

          reports-token: ${{ secrets.TRUESPEC_REPORTS_TOKEN }}

Add TRUESPEC_REPORTS_TOKEN as a repository secret.

The report shows severity, endpoint context, and schema-level diffs so reviewers can focus on breaking risk.

Summary

Breaking: 5 | Warning: 3 | Info: 3

BREAKING (5)

- Removed operation DELETE /v1/users/{id}

- Removed response 404 for GET /v1/users

- Enum changed at response.200.body.status

- Removed field response.200.body.email

- Type changed at request.body.price

WARNING (3)

- New required parameter query:dryRun for PUT /v1/plans

- Request body is now required for PUT /v1/plans

- New required field request.body.name

INFO (3)

- Added operation GET /v1/billing

- Added response 422 for GET /v1/users

- Added field response.200.body.tier

We are onboarding teams in batches. Join the waitlist and we will share new capabilities as soon as they are ready.