Keystone

Merge requests that break together, blocked together. Keystone uses GitLab Orbit graphs to catch silent semantic collisions before they ship.

Comment

Inspiration

Every CI pipeline catches what Git can see — files changed, lines touched. But two merge requests can pass every check, touch completely different files, and still break production together because they share a semantic dependency that no diff can reveal.

Keystone was built to fix that blind spot. The question was simple: what if the reviewer could see the relationships between symbols, not just the files?

What it does

Keystone is a merge request intelligence layer built on GitLab's Orbit dependency graph. It catches silent semantic collisions — cases where two MRs are independently safe but jointly destructive.

  • Command Center: Live dashboard showing 262 symbol definitions, max blast radius of 12, and real-time silent-collision detection across open MRs.
  • Reviewer Cockpit: Loads any MR pair, renders blast-radius rings, identifies overlapping dependents (e.g. compute_blast_radius × verify → 5 shared dependents), and issues a HOLD or APPROVE verdict with an AI-generated explanation.
  • Audit Ledger: Tamper-evident SHA-256 chain of every Keystone decision. Simulate tamper → CHAIN BROKEN. Restore chain → CHAIN VERIFIED.
  • CLI Agent: python skills/keystone/run_review.py review-mr --sample MR-204 --format markdown generates a real MR comment with blast radius, collision count, and block/approve recommendation.
  • GitLab Duo AI Catalog skill: Keystone is published as a reusable AI skill (skills/keystone/SKILL.md) callable from any GitLab Duo workflow.

How we built it

  • Backend: Python + FastAPI, deployed on Render. Parses the committed Orbit graph (web/data.json, 517 KB), computes blast radii, detects collisions, and signs audit entries.
  • Frontend: Vanilla JS single-page app hosted on GitHub Pages. Zero framework dependencies — deterministic static bundle.
  • Orbit graph: Built from real Python AST analysis across the Keystone codebase. 262 definitions, edges representing call/import relationships.
  • AI skill layer: .gitlab/agents/keystone/agent.yml + skills/keystone/run_review.py wired to the GitLab Duo Agent Platform.
  • Test suite: 165 tests, 2 skipped — covering blast-radius computation, collision detection, audit chain integrity, and CLI output format.

Challenges we ran into

  • Orbit graph fidelity: Getting the AST parser to produce a graph that matched real call relationships (not just imports) required several iterations of the edge-building logic.
  • Audit chain determinism: Making the SHA-256 chain reproducible across deploys without a database meant encoding the decision log in a canonical JSON format before hashing.
  • GitLab CI identity verification: GitLab requires a payment card on file to run shared runners — blocked CI on GitLab side. Mitigated by running full CI on GitHub Actions and keeping both remotes in sync.
  • Static bundle size: Keeping web/data.json deterministic and under 520 KB while encoding the full 262-symbol Orbit graph with all edge weights.

Accomplishments that we're proud of

  • 165 tests passing with zero flaky failures across blast-radius, collision, audit, and CLI layers.
  • A live backend at keystone-zt6c.onrender.com returning real Orbit data with sub-200ms response times.
  • A tamper-evident audit ledger that actually works — simulate a tamper and watch the chain break in real time.
  • The CLI generates a real, paste-ready GitLab MR comment with accurate numbers from the committed graph.
  • The entire frontend is framework-free and loads in under 1 second on cold cache.

What we learned

  • GitLab's Orbit graph is a powerful but underused primitive. Most tools stop at file diffs; symbol-level dependency graphs unlock a completely different class of review intelligence.
  • Audit integrity is not just a feature — it's a trust primitive. Reviewers need to know that a HOLD verdict hasn't been tampered with before they act on it.
  • Static-first architecture (GitHub Pages + Render) is surprisingly capable for a showcase-grade tool: no infrastructure ops, deterministic deploys, zero cold-start on the frontend.

What's next for Keystone

  • Real-time MR webhook: Hook into GitLab's MR events API to run Keystone automatically on every opened MR and post the review comment via the GitLab Duo skill.
  • Cross-repo Orbit: Extend the graph to span multiple repositories — monorepo and microservice teams have the same collision problem across service boundaries.
  • Reviewer dashboard: A persistent GitLab sidebar panel showing live blast-radius rings for the MR currently open in the browser.
  • Orbit graph versioning: Track how the dependency graph evolves across commits so reviewers can see why the blast radius of a symbol grew between MR-200 and MR-204.

Built With

Share this project:

Updates