Contract Sentinel

Catch breaking API contract changes before they reach production, with deterministic checks, GitLab CI evidence, and GitLab Duo-assisted analysis.

Comment

Inspiration

Shipping code is only half the job. Once an API is in use, even a small change can break applications that depend on it.

A provider might remove a required field, change a response structure, or introduce an incompatible contract without realizing the consequences until a downstream consumer fails.

I built Contract Sentinel to make those compatibility risks visible earlier, using deterministic checks, GitLab CI, and AI-assisted analysis.

The idea is simple: don't just tell developers that a pipeline failed. Help them understand what changed, why it matters, and what evidence supports the conclusion.

What it does

Contract Sentinel is an API contract compatibility checker that identifies breaking changes and produces reproducible evidence for developers reviewing those changes.

It demonstrates four core capabilities:

  • Deterministic contract checking: Evaluates compatible and incompatible API contracts, including malformed input.
  • GitLab CI integration: Runs contract checks in a real GitLab pipeline and produces machine-readable evidence artifacts.
  • GitLab Duo-assisted analysis: Uses a GitLab Duo Agent Platform session to generate a provisional explanation of contract-checking evidence.
  • Independent evidence validation: Checks captured GitLab API responses separately from the agent's conclusions.

In the demonstrated breaking case, a required name field is missing. The checker identifies the incompatibility and returns exit code 1.

The corresponding GitLab CI job fails intentionally. This is the expected result of detecting a breaking contract, not an unexpected infrastructure failure.

How I built it

I developed Contract Sentinel using TypeScript and Node.js, with GitLab as the repository, CI, and agent-workflow platform.

The implementation includes:

  1. A deterministic contract checker with explicit compatibility outcomes.
  2. Fixtures representing compatible, breaking, and malformed contract inputs.
  3. Automated tests for contract-checking behavior.
  4. GitLab CI jobs that execute the checker and publish JSON evidence artifacts.
  5. A GitLab Duo Agent Platform workflow for evidence-aware analysis.
  6. An independent validator that evaluates captured GitLab API evidence.

The checker can run locally without relying on an AI model to determine whether a contract is compatible.

GitLab Duo adds an explanatory layer, while the deterministic checker and independent validator provide separate evidence that can be inspected and reproduced.

Challenges I ran into

One major challenge was distinguishing a successful AI-generated explanation from independently verified evidence.

An agent can produce a plausible report without its visible trace proving every underlying API retrieval.

Rather than treating the report as definitive, I separated the evidence into different confidence levels:

  • Local checker results.
  • Actual GitLab CI job results and published artifacts.
  • GitLab Duo session output.
  • Independent validation of captured GitLab API responses.

The demonstrated Duo session successfully produced a provisional analysis, but its visible trace does not prove all six exact resource retrievals or the underlying artifact bytes.

The independent validation therefore preserves the explicit status duoSessionProvenance: NOT_PROVEN.

Another challenge was making an intentionally failing CI job understandable. Contract Sentinel treats that failure as a useful signal: a breaking API change was detected.

Accomplishments

  • Built a working deterministic contract-checking prototype.
  • Verified compatible and breaking cases through GitLab CI.
  • Published machine-readable JSON evidence artifacts.
  • Demonstrated a GitLab Duo Agent Platform analysis session.
  • Added independent evidence-consistency validation.
  • Preserved a transparent distinction between confirmed results and unproven agent provenance.
  • Created a reproducible demonstration covering the complete workflow.

The project demonstrates how automated compatibility checks and AI-assisted explanations can complement one another without confusing an agent's claims with independently verified facts.

What I learned

Building Contract Sentinel reinforced an important principle: AI-assisted developer automation becomes more trustworthy when its conclusions can be checked against independent evidence.

I also learned how to structure contract-checking results for CI, use intentional pipeline failures as actionable signals, and communicate the limits of agent execution traces.

What's next

The next steps for Contract Sentinel are:

  • Support more complex API schemas and compatibility rules.
  • Expand contract comparison and reporting capabilities.
  • Improve merge request feedback and developer-facing explanations.
  • Strengthen GitLab Duo retrieval provenance and artifact verification.
  • Explore broader integration into continuous API governance workflows.

The long-term goal is to make breaking API changes easier to detect, explain, and prevent throughout the software delivery lifecycle.

Built by Abdulbakky Agboola (0xBaqi / Baronal)

Project: https://gitlab.com/gitlab-ai-hackathon/transcend-october-2026/43431981/showcase

Demo: https://youtu.be/6BX_qGMVkK4

Built With

Share this project:

Updates

Submission history