Block PRs on Breaking API Changes: CI/CD Gating with API Contract Guardian

The Problem: Breaking Changes That Review Misses

When you rename a field, change a type, or remove an endpoint from your OpenAPI spec, you're making a breaking change — existing clients will crash or silently misinterpret responses. Code review catches some of these, but not reliably:

• Type changes are invisible in diff. Changing age from integer to string is a one-line YAML diff. The reviewer sees the line changed. They don't always register that every client parsing that field now breaks.
• Required-property additions are sneaky. Adding phone as a required field to User doesn't break your server — it breaks every client that doesn't send phone on create.
• Removed endpoints are easy to miss in large specs. A spec with 40 endpoints doesn't fit on screen. Removing DELETE /users/{id} in the middle of a 2,000-line YAML file is easy to overlook.
• Response-format changes break silently. Changing a 200 response from application/json to application/xml looks benign in review. Every JSON client now gets parse errors.

The fix is mechanical: automate breaking-change detection in CI. If a PR introduces a breaking change, the build fails. No human review required.

Quick Start: Detect Breaking Changes in One Command

Step 1: Install API Contract Guardian

pip install api-contract-guardian

Step 2: Compare Two Spec Files

# Compare your current spec against the proposed change
api-contract-guardian check openapi-v1.yaml openapi-v2.yaml

# Clean output -- no breaking changes:
# ✓ No breaking changes detected

# Breaking change output:
# ✗ BREAKING CHANGES DETECTED
#
# 1. Removed endpoint: DELETE /users/{id}
# 2. Changed type: User.age (integer -> string)
# 3. Required property added: User.phone
#
# Exiting with code 1.

Step 3: Generate a Migration Guide

# Auto-generate a migration guide for API consumers
api-contract-guardian migrate openapi-v1.yaml openapi-v2.yaml --output MIGRATION.md

# MIGRATION.md contains:
# - Each breaking change with before/after
# - Required client updates for each change
# - Suggested migration timeline

The Six Breaking-Change Categories

API Contract Guardian checks for six categories of breaking changes. Each one is a hard incompatibility — existing clients will break:

Category	Example	Why It Breaks Clients
Removed endpoint	DELETE /users/{id} removed	Any client calling that endpoint gets 404
Removed property	email removed from User schema	Clients that read user.email get undefined/null
Changed type	age changed from integer to string	Client-side type assertions fail; JSON parsing breaks
Required property added	phone now required in User	Existing create requests missing phone get 400
Renamed field	name renamed to fullName	Clients reading name get undefined
Response format changed	200 response type changed	Response parsing fails on the client side

CI/CD Integration: GitHub Actions

The check command exits with code 1 when breaking changes are found. This makes it a natural CI gate:

# .github/workflows/api-contract-check.yml
name: API Contract Check

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

jobs:
  contract-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Need full history for branch diffing

      - name: Install API Contract Guardian
        run: pip install api-contract-guardian

      - name: Check for breaking changes
        run: |
          # Compare the PR branch spec against main
          git checkout origin/main -- openapi.yaml
          cp openapi.yaml openapi-main.yaml
          git checkout - -- openapi.yaml

          api-contract-guardian check openapi-main.yaml openapi.yaml

      - name: Generate migration guide (on failure)
        if: failure()
        run: |
          api-contract-guardian migrate openapi-main.yaml openapi.yaml \
            --output MIGRATION.md

      - name: Upload migration guide
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: migration-guide
          path: MIGRATION.md

When a PR introduces a breaking change:

1. The check step fails with a non-zero exit code
2. GitHub marks the PR as "Checks failed"
3. The migrate step generates MIGRATION.md
4. The migration guide is uploaded as an artifact for the PR author

CI/CD Integration: GitLab CI

# .gitlab-ci.yml
api-contract-check:
  stage: test
  image: python:3.12
  rules:
    - changes:
        - openapi.yaml
  script:
    - pip install api-contract-guardian
    - |
      # Get the target branch spec
      git checkout origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME -- openapi.yaml
      cp openapi.yaml openapi-base.yaml
      git checkout $CI_COMMIT_SHA -- openapi.yaml
    - api-contract-guardian check openapi-base.yaml openapi.yaml
    - api-contract-guardian migrate openapi-base.yaml openapi.yaml --output MIGRATION.md
  artifacts:
    when: on_failure
    paths:
      - MIGRATION.md

Git Branch Diffing: Compare Without Checking Out Files

The examples above manually check out both versions of the spec. For a simpler workflow, you can compare specs directly between branches:

# Compare current branch against main
api-contract-guardian check --base main --head feature/user-endpoints

# Compare two tags
api-contract-guardian check --base v1.2.0 --head v1.3.0

# Machine-readable output for custom CI logic
api-contract-guardian check --base main --head feature/user-endpoints --format json

# JSON output:
# {
#   "breaking_changes": [
#     {
#       "category": "removed_endpoint",
#       "endpoint": "DELETE /users/{id}",
#       "severity": "critical"
#     },
#     {
#       "category": "changed_type",
#       "schema": "User",
#       "field": "age",
#       "from": "integer",
#       "to": "string",
#       "severity": "critical"
#     }
#   ],
#   "summary": {
#     "total": 2,
#     "critical": 2,
#     "warning": 0
#   }
# }

Output Formats

API Contract Guardian supports multiple output formats for different use cases:

Command	Formats	Best For
check	rich, json, yaml	CI gating, programmatic consumption
migrate	rich, json, yaml, markdown	Consumer migration guides, PR documentation
diff	rich, json, yaml, markdown	Full change log including non-breaking changes

# Markdown migration guide for PR description
api-contract-guardian migrate openapi-v1.yaml openapi-v2.yaml --format markdown --output MIGRATION.md

# YAML diff for programmatic processing
api-contract-guardian diff openapi-v1.yaml openapi-v2.yaml --format yaml --output contract-diff.yaml

# JSON check for custom CI logic
api-contract-guardian check openapi-v1.yaml openapi-v2.yaml --format json --output check-result.json

Real-World Scenario: Microservice Contract Enforcement

Without contract checking:

• Team A renames name to fullName in the User spec. Deploys on Friday. Team B's order enrichment pipeline breaks silently — orders ship with blank customer names. Nobody notices until Monday's customer complaints.

With API Contract Guardian in CI:

# Team A's CI pipeline
api-contract-guardian check openapi-main.yaml openapi.yaml

# Output:
# ✗ BREAKING CHANGES DETECTED
#
# 1. Renamed field: User.name -> User.fullName
#
# Exiting with code 1. PR cannot merge.

# Team A generates the migration guide
api-contract-guardian migrate openapi-main.yaml openapi.yaml --format markdown

# Shares the guide with Team B and Team C:
# - Update all references from user.name to user.fullName
# - If using a shared client SDK, regenerate from new spec
# - Migration deadline: coordinate with consuming teams before merge

The PR is blocked until Team A coordinates the migration with Teams B and C. The breaking change still ships — but with a documented, planned migration path instead of a Friday-night fire drill.

OpenAPI 3.x Support

API Contract Guardian supports both OpenAPI 3.0.x and 3.1.x:

• 3.0.x — The most widely adopted version. Used by Swagger UI, Redoc, and most API gateways.
• 3.1.x — The latest spec with full JSON Schema alignment. Adds webhooks, jsonSchemaDialect, and changes to nullable handling.

Both versions are treated correctly for breaking-change detection. A nullable: true in 3.0.x and type: ["string", "null"] in 3.1.x are both recognized as nullable fields — a change from nullable to non-nullable is flagged as a breaking change.

Combining with Other DevForge CI Gates

API Contract Guardian is one of several DevForge tools that gate CI pipelines. Together they form a safety net that catches problems before deploy:

Tool	What It Catches	CI Gate Command
API Contract Guardian	Breaking API changes (removed endpoints, changed types, new required fields)	api-contract-guardian check
ConfigDrift	Config drift between environments	configdrift check
DeadCode	Dead code in React/Next.js projects	deadcode check
APIAuth	Expired or revoked API keys	apiauth audit
DeployDiff	Infrastructure cost and config changes	deploydiff check

Install API Contract Guardian

pip install api-contract-guardian

# Check your first spec pair
api-contract-guardian check openapi-old.yaml openapi-new.yaml

# Generate a migration guide
api-contract-guardian migrate openapi-old.yaml openapi-new.yaml --output MIGRATION.md

# Full diff including non-breaking changes
api-contract-guardian diff openapi-old.yaml openapi-new.yaml

Star API Contract Guardian on GitHub

Related Reading

• Catch Breaking API Changes in CI — overview of API contract testing approaches
• OpenAPI Diff Tools Compared — API Contract Guardian vs oasdiff vs optic vs spectral
• Block Deployments on Config Drift — ConfigDrift CI gating tutorial
• Fail CI on Dead Code — DeadCode CI gating tutorial
• Zero to CI Safety Net — wire all DevForge gates into one pipeline