Contract Agents

Breaking API changes, without the breakage. A team of GitLab Duo agents plans, migrates and retires old versions while you approve the outcome.

Comment

Inspiration

In any company with many services, one team renames an API field. Their tests pass. CI is green. Then a different team's service, which reads that field, breaks in production.

The safe way to change an API is well known: expand, migrate, contract. Publish the new version next to the old one, move every consumer, prove nobody reads the old version anymore, then remove it. Almost nobody does it properly, because it means weeks of chasing other teams, watching dashboards and remembering to clean up.

That kind of patient coordination is exactly what agents are good at. So we built a team of GitLab Duo agents that does it for you.

Who it is for: platform and backend teams that run many services and share APIs between them.

What it does

Contract Agents gives every service its own GitLab Duo agent, plus three agents that look after the whole system. When a merge request would break a published API contract:

  1. The contract-check job blocks the MR. The failed pipeline wakes the Contract Steward.
  2. The Steward asks every consumer's agent: does this break you? Each agent reads its own code and answers with file and line evidence.
  3. The Steward writes a migration plan as a GitLab issue.
  4. The Shipping Agent rewrites the MR into the safe Expand step: the new version is published next to the old one, so nobody breaks.
  5. Duo Code Review, tests, SAST, secret detection, dependency scanning, staging and DAST run. Then the Governance agent checks the release against a written policy and posts Verdict: PASS or BLOCK.
  6. A human approves production with one click. That is the only required human step.
  7. The Monitor agent reads real production traffic per consumer and per version, and tells each consumer's agent to migrate. Each agent writes its own migration MR.
  8. Silence is not proof. Monitor only says SAFE TO CONTRACT when every consumer is seen on the new version, with zero reads of the old one, over a full window.
  9. The Shipping Agent removes the old version, Monitor says COMPLETE, and the Steward closes the issue with a full timeline.

Nothing breaks. Nobody chases anybody. One human approval per production release.

This is Supervised autonomy: the agents run the whole multi step workflow, clear gates and decide when to move on. The human approves the outcome, not each step.

All 9 DevSecOps stages are covered:

Stage How
Plan Steward writes the migration issue, plan and final timeline
Create Agents write the expand, migration and contract MRs
Verify Unit and contract tests, contract check, smoke tests, Duo Code Review
Package Cloud Build images in Google Artifact Registry
Secure SAST, secret detection, dependency scanning, DAST, Governance blocks on critical findings
Release Staging first, Governance gated production job, a GitLab Release per deploy
Configure Cloud Run services as code, config per environment
Monitor Per consumer, per version production usage read by the Monitor agent
Govern Written deprecation policy, enforced verdicts, audit trail in issues

It really ran, live, twice, against real services on Google Cloud Run:

  • A live migration, recorded for the video: renaming etaDays to deliveryDays went from a blocked MR to a retired old version in about two hours, with zero production errors.
  • The agents negotiated on their own: Storefront said AFFECTED, Notifications said NOT AFFECTED, and the Shipping Agent rewrote the change safely.
  • Both consumers migrated themselves after Monitor saw them still using the old version in production.
  • The old version was removed only with proof: zero reads over a full window.
  • The first run had real failures, caught by supervision: Governance blocked a release over critical vulnerabilities, Monitor once retired too early and we fixed its rule, and Duo Code Review caught real bugs in agent MRs.

How we built it

GitLab Duo Agent Platform

  • 6 custom flows in .gitlab/duo/flows/: Contract Steward, Storefront Agent, Notifications Agent, Shipping Agent, Monitor and Governance.
  • Triggers: pipeline events (a failed pipeline wakes the Steward, a passed usage pipeline wakes Monitor) and mentions (the pipeline mentions Governance).
  • Reused catalog flow: GitLab Duo Code Review reviews every MR an agent opens.
  • Agents that must talk to each other run in sequence inside one flow, each with its own prompt, tools and voice.

The pipeline is the hands, the agents are the brains

  • CI jobs collect evidence (a schema diff report, a usage report per consumer, scan results, smoke tests), and agents read it and decide.
  • The human gate is enforced in code: the approve-production job fails unless Governance wrote Verdict: PASS.
  • Every agent must show evidence: file and line, job log, or report field.

The demo shop and Google Cloud

  • Three TypeScript (Fastify) services: shipping publishes the API, storefront and notifications consume it. Every call sends who is calling and which version, so shipping can count usage per consumer.
  • 38 unit and contract tests, with reports in GitLab.
  • Cloud Build builds the images into Artifact Registry, and Cloud Run runs staging and production, all defined as code in the repo.

Challenges we ran into

  • Flows cannot wake other flows. We redesigned the system so agents talk inside one flow, and human actions start each phase.
  • Monitor's first rule was wrong. No traffic is not the same as no consumers. It now needs positive proof from every consumer.
  • The agents first assumed one specific version change. We generalised them so any version change works, then proved it with a second live run.
  • Two releases raced on the same Cloud Run setting. The pipeline caught it and a retry fixed it.
  • Governance even blocked our own setup MR for a missing issue link, exactly as the policy says.

Accomplishments that we're proud of

  • Two full migrations in real production with zero breakage.
  • Agents that disagree, block and catch real bugs, not just agents that say yes.
  • A paper trail anyone can click through: every decision is a note with evidence.
  • Every one of the 9 DevSecOps stages is touched by real automation, running on Google Cloud.

What we learned

Supervised autonomy works best when every agent must show its evidence, and when the gate to production is enforced by the pipeline, not just described in a prompt. Agents also need to be allowed to say no: the most valuable moments were a Governance BLOCK and a reviewer catching a bug.

What's next for Contract Agents

  • Support many contracts and many consumers at once
  • A deploy lock so releases can never race
  • A live contract status page per consumer
  • Packaging the flows so any GitLab project can adopt them

How to verify

Honest notes

  • The observation window is 10 minutes for the demo. The policy uses 7 days in real life.

Built With

Share this project:

Updates

Submission history