I Built a GitHub App That Catches Breaking API Changes Before They Ship

Last week I spent 10 hours debugging a production issue. Someone had removed a field from a TypeScript interface. Three other files were using it. Nobody caught it in code review because nobody knew those files existed.

That's when I decided to build BreakShield CI.

What it does

BreakShield CI is a GitHub App that automatically analyzes every pull request for breaking API changes. It runs in the background — no config, no CLI, no YAML.

When it finds something, it posts a comment directly in your PR:

• Which interface or endpoint changed
• What exactly changed (removed field, type change, optional → required)
• Which files and lines in your codebase actually use the changed API
• A risk level: SAFE / LOW / MEDIUM / HIGH / CRITICAL

HIGH and CRITICAL risk PRs get a failing Check Run that blocks merge.

How it works technically

The interesting part is the analysis engine.

Most tools use regex to find breaking changes. BreakShield CI uses a full TypeScript AST via ts-morph. This means it actually understands your code — not just searches for strings.

For every changed .ts file in a PR it:

1. Parses both the before and after version into an in-memory AST
2. Extracts all exported interfaces, type aliases, and functions
3. Diffs them to find breaking changes
4. Searches the codebase for files that use the changed API
5. AST-verifies each match — direct access, destructuring, type annotations
6. Scores each finding by confidence (0–100)

For OpenAPI specs it uses @apidevtools/swagger-parser to dereference all $ref pointers and diffs paths, parameters, request bodies, and response schemas.

What it detects

Breaking (blocks merge on HIGH/CRITICAL):

• Removed field from interface
• Changed field type
• Optional → required
• Removed endpoint
• Removed function parameter
• Added required field to request body

Safe (informational only):

• Added optional field
• New endpoint added

The confidence scoring

Every finding needs evidence. No evidence = no warning.

Evidence is scored by usage type:

• obj.field direct access → 90%
• const { field } = obj destructuring → 80%
• : UserResponse type annotation → 80%
• GitHub Search hit without AST verification → 35%

Low confidence noise is filtered automatically.

Try it

BreakShield CI is free during beta. Install it in 30 seconds:

👉 breakshield-ci.vercel.app

Would love feedback from anyone working with TypeScript APIs or microservices.
`

`