OrbitGuard

Know what breaks… before you ship it

Comment

Inspiration

Every developer has merged a "small change" that quietly broke something else — a function that another module silently depended on, a separate project that consumed an API, a check that protected something more important than it looked.

The problem isn't that developers don't want to know — it's that finding out requires manually tracing every function call, every cross-project dependency, every linked issue. Nobody has time for that before a 4pm merge deadline.

GitLab Orbit's knowledge graph already understands all of those relationships. It seemed like exactly the right foundation to build an agent that does that tracing automatically — and explains it like a human, not a static analyzer.

We also wanted to design for how developers actually build today: with AI editors like Cursor, Copilot, and Windsurf doing a huge share of the typing. So instead of just flagging a risk, OrbitGuard had to hand back something genuinely actionable — a fix the developer could literally paste into their AI tool and run.

What it does

OrbitGuard is a GitLab Duo flow that runs the moment a merge request is opened or mentioned. It:

  1. Scans the MR using GitLab Orbit's knowledge graph — mapping every function, file, and cross-project dependency the change touches
  2. Explains the risk in plain English — no jargon, written like a smart friend texting you a heads-up
  3. Suggests a safer alternative that achieves the same result with a smaller blast radius
  4. Generates a Vibecode Fix — a ready-to-paste prompt for AI coding tools that implements the safer version
  5. Asks for approval before touching anything: proceed, apply the fix, or skip

It's the difference between a tool that tells you something is wrong, and one that helps you actually fix it — on your terms.

How we built it

OrbitGuard is a three-agent custom flow on the GitLab Duo Agent Platform, orchestrated through a single flow.yaml:

  • orbit_scanner — queries Orbit's knowledge graph for changed files, downstream callers, cross-project dependencies, linked issues, and recent pipeline failures
  • risk_analyzer — takes the raw scan and translates it into a plain-English risk summary, a safer alternative, and the Vibecode Fix prompt
  • decision_handler — posts the formatted comment to the MR, waits for the developer's reply, and executes the chosen action (including committing the safer fix directly via the GitLab API)

We iterated heavily on the language of the output. Early versions read like a static analysis report — technically correct, but nobody wants to read it mid-sprint. We rewrote every prompt so the tone matched how a thoughtful teammate would actually flag a concern: direct, low-jargon, and focused on real consequences ("checkout might break," not "downstream coupling detected").

Challenges we ran into

  • Custom flows require a group namespace, not a personal one — we had to migrate the entire project into a group partway through, which meant re-checking every prerequisite from scratch.
  • GitLab Duo Agent Platform features are still in beta, so some configuration paths (like enabling flows from the AI Catalog) weren't where the docs implied — we had to navigate around UI inconsistencies and trial-and-error our way to the right settings.
  • Flow YAML validation errors were sparse on detail. Chaining outputs between agents (e.g., passing the scanner's findings into the analyzer) required learning the exact allowed inputs.from targets through repeated failed deployments rather than documentation alone.
  • Getting the tone right took multiple rewrites. The first version of the MR comment was accurate but unreadable under time pressure — we had to specifically design for developers skimming on a phone mid-standup.

What we learned

  • GitLab Orbit's knowledge graph is genuinely powerful for impact analysis — most of OrbitGuard's value comes from connecting data Orbit already exposes (file references, pipeline history, linked issues) rather than computing anything novel ourselves.
  • Plain-language output isn't a cosmetic choice — it directly determines whether a developer reads and acts on a recommendation, especially in fast-moving "vibecoding" workflows where AI editors handle most implementation.
  • Multi-agent flows benefit from narrow, single-purpose agents. Splitting scanning, analysis, and decision-handling into separate agents made debugging dramatically easier than one large agent trying to do everything.

What's next for OrbitGuard

  • Auto-trigger on "ready for review" instead of requiring a manual mention, so blast radius checks happen by default
  • Multi-language support beyond the languages currently indexed by Orbit
  • Severity-based routing — auto-blocking merges only for HIGH risk changes, while LOW risk changes get a lightweight, non-blocking note
  • Team-level analytics — surfacing which files/modules generate the most blast radius warnings over time, to guide refactoring priorities

Built With

Share this project:

Updates