Orbit Nexus: Context-Driven GitLab Duo Agent Skills

Orbit Nexus is a developer tool suite exposing specialized AI skills on the GitLab Duo Agent platform. Driven by GitLab Orbit graph context, it automates guardrails, deprecation, & incidents.

Comment

💡 Inspiration

AI coding assistants are incredibly powerful, but they often struggle when drop-in edits affect the broader codebase. Without deep system context, an AI might write a syntactically correct function that silently breaks an API downstream, violates architectural design rules, or ignores active system incidents.

We were inspired to build Orbit Nexus to bridge the "context gap" in AI-assisted development. By leveraging GitLab Orbit's queryable repository graphs, we wanted to build a suite of tools that gives AI agents the "eyes" to see how files connect, trace the ripple effects of code changes, and keep software architectures clean and compliant automatically.

🔍 What it does

Orbit Nexus is a developer control center and a set of specialized AI skills designed for the GitLab Duo Agent Platform. It exposes four core, context-driven tools:

  1. Architecture Explorer: A visual React Flow dashboard displaying a real-time, interactive graph of codebase dependencies, complete with line counts and unit-test coverage overlays.
  2. Delete Simulator: Previews the blast radius of deprecating or deleting any module, scanning imports to list every downstream file, REST endpoint, and pipeline configuration that will break.
  3. Architecture Guardrail: Analyzes merge request (MR) diffs against strict layout guidelines, automatically scoring compliance, detecting circular dependencies, flagging domain boundaries, and blocking builds if the score drops below a customizable threshold.
  4. Incident Investigator: Correlates production stacktraces with the dependency graph to immediately highlight culprit files and output structured, AI-suggested code fixes.

All features are accessible via a premium dashboard, a command-line interface (CLI), and a pre-configured GitLab CI/CD gating pipeline.

🛠️ How we built it

We structured Orbit Nexus to demonstrate the full capabilities of modern AI and developer workflows:

  • The AI Core: Built on the modern Google GenAI SDK using gemini-2.5-flash-lite to optimize for speed, cost-effectiveness, and precise structured output mapping using Pydantic JSON schemas.
  • Context Ingestion: Developed a dual-mode Orbit Context Manager that queries remote GitLab Orbit graph endpoints (/api/v4/orbit/query) using ORBIT_API_KEY, dynamically falling back to a local, high-performance AST (Abstract Syntax Tree) scanner to compile dependency graphs on-the-fly.
  • The Web App: Crafted a highly responsive Next.js frontend styled with modern UI design principles, featuring dynamic sidebars, smooth animations, and interactive React Flow node graphs.
  • Agentic Integrations: Created an OpenAPI 3.0-compliant schema and defined Duo Platform specifications in GITLAB_DUO_SKILL.md to expose these endpoints as callable AI skills.
  • DevOps Pipelines: Built backend/cli.py and a .gitlab-ci.yml script to integrate the guardrails directly into active GitLab CI runs.

🚧 Challenges we ran into

  • Accessing the Orbit Remote Graph: Not all repositories or environments have the remote GitLab Knowledge Graph feature active, resulting in API authentication/authorization errors. We resolved this by building a fallback local AST parser that reconstructs module imports and builds equivalent codebase graphs locally, providing a seamless user experience.
  • Model Selection and Schema enforcement: Earlier models struggled to consistently follow strict Pydantic schemas or returned 404s. Migrating to the brand-new gemini-2.5-flash-lite solved this, giving us fast, reliable, structured JSON responses at a fraction of the cost.
  • Submodule Staging Issues: The frontend setup originally contained its own nested git configuration, which threatened to break the main repository tree. We resolved this by cleaning up the staging index, removing internal .git directories, and restructuring the codebase as a clean, unified repository.

🏆 Accomplishments that we're proud of

  • Interactive Visualization: The visual representation of codebase dependencies in the Architecture Explorer makes navigation instantly understandable.
  • Automated CI/CD Gates: Building a functional CLI tool that hooks directly into GitLab CI pipelines to enforce architectural compliance feels incredibly satisfying.
  • Cost Efficiency: Harnessing gemini-2.5-flash-lite for complex parsing tasks proved that high-quality structured AI generation doesn't have to be expensive.
  • Exposing Clean Duo Skills: Delivering a clean OpenAPI schema and a detailed integration specification makes Orbit Nexus ready to plug directly into the GitLab Duo Agent Platform catalog.

📚 What we learned

  • The Power of Graph-Based Context: Feeding LLMs structured graph data (like parent-child dependencies or blast-radius maps) dramatically improves their reasoning accuracy compared to raw source code prompts.
  • Structured Output Optimization: Enforcing strict JSON response models is essential for building reliable agent workflows that interface with frontend state and CI/CD tools.
  • Adaptive Integrations: Providing reliable fallbacks (like our local AST scanner) is critical when building tools that interact with cutting-edge, remote enterprise APIs.

🚀 What's next for Orbit Nexus

  • Deeper Duo Agent Actions: Fully register Orbit Nexus on the GitLab Duo Agent platform to allow chat agents to execute actions (like triggering a delete simulation directly from a GitLab issue thread).
  • Multi-Language AST Parsing: Expand our fallback AST scanner to support TypeScript, Go, and Rust dependencies alongside Python.
  • Predictive PR Reviewing: Utilize historical git commits to let the Delete Simulator predict which teams or authors should be added as reviewers based on the files affected in the blast radius.

Built With

Share this project:

Updates