Orbit CI Troubleshooter

AI agent that diagnoses failing GitLab CI pipelines in 2 minutes using GitLab Orbit knowledge graph — from red pipeline to root cause automatically.

Comment

Inspiration

Every developer has lost hours to a failing CI pipeline. You open the logs — 500+ lines of gibberish. You scroll, guess, retry, ping teammates. Nothing works. Hours wasted. Shipping blocked.

The real problem is that CI failure logs give you symptoms, not root causes. No tool connects the failure back to the exact commit, file, or dependency that caused it — especially across multiple projects.

When I discovered GitLab Orbit — a live, queryable knowledge graph of your entire codebase connecting pipelines, commits, files, MRs, and dependencies — I immediately saw the solution. This is exactly the context layer missing from CI debugging.

What it does

Orbit CI Troubleshooter is an AI agent on GitLab Duo Agent Platform that automatically diagnoses failing CI pipelines using 3 custom skills:

🔍 Log Inspector Skill Reads 500+ lines of raw CI job logs and extracts the exact error message, exit code, failed job name, and affected file.

🧠 Orbit Context Skill Queries GitLab Orbit knowledge graph to find: → Which commits touched the failing files → Which MR introduced those commits → Whether the same failure happened before → Blast radius — other projects affected

📝 Diagnosis Writer Skill Combines log analysis + Orbit findings and posts a structured diagnosis comment directly on the MR or pipeline with: → Root cause (1 sentence) → Evidence (exact commit/file/MR) → Blast radius (other affected projects) → Fix suggestion (exact change needed)

Developer just clicks "Fix pipeline with Duo" — agent does the rest in under 2 minutes.

How we built it

Built entirely on GitLab Duo Agent Platform using:

  1. Custom Agent — Created in GitLab AI → Agents with a detailed system prompt defining investigation workflow

  2. Three Custom Skills (MD files) stored at .gitlab/agents/skills/:

    • log-inspector.md
    • orbit-context.md
    • diagnosis-writer.md

  3. GitLab Orbit Knowledge Graph — Used via the agent's built-in Orbit integration to query pipelines, commits, files, MRs, and cross-project dependencies

  4. GitLab Duo Flow YAML — Defined in .gitlab/duo-flows/ci-troubleshooter.yml to orchestrate the 3-step investigation pipeline

  5. Published to AI Catalog for public discovery and use

    Challenges we ran into

  6. Orbit Indexing — Personal projects are not automatically indexed into Orbit knowledge graph. The agent works best on projects within the GitLab hackathon namespace where Orbit indexing is active.

  7. Skill chaining — Getting the agent to follow a strict log-inspector → orbit-context → diagnosis-writer order required careful system prompt engineering.

  8. Empty graph responses — When Orbit has no data for a project, the agent needed graceful fallback behavior to still provide useful diagnosis from logs alone.

  9. Branch protection — Workspace project had protected main branch, required working through MR flow to test the full pipeline failure scenario.

    Accomplishments that we're proud of

    ✅ Built a fully working agent on GitLab Duo Agent Platform with 3 custom skills in under 2 weeks

✅ Agent correctly follows log-inspector → orbit-context → diagnosis-writer workflow every single time

✅ Successfully triggered "Fix pipeline with Duo" button on a real failing pipeline in the hackathon workspace

✅ Published to GitLab AI Catalog publicly — any team can now add this agent to their project

✅ Agent produces structured diagnosis with root cause, evidence, blast radius, and fix suggestion — exactly the format developers need

What we learned

  1. GitLab Orbit is a fundamentally different approach to AI-assisted development — giving AI actual codebase context instead of just text.

  2. Skill-based agent design (small focused skills vs one giant prompt) produces much more reliable and predictable agent behavior.

  3. The "Fix pipeline with Duo" button is a powerful native GitLab trigger — agents that hook into existing GitLab UI patterns get adopted faster.

  4. Blast radius analysis across projects is the killer feature — something no existing CI tool does, only possible with Orbit's knowledge graph.

    What's next for Orbit CI Troubleshooter

  5. Flaky Job Watcher — Automatically detect jobs that fail intermittently over time and suggest retry configs or test isolation fixes

  6. Multi-project Blast Radius — When a dependency bumps version, automatically find ALL pipelines across ALL projects that will break

  7. Auto Fix MR — When agent is confident about the fix, automatically create a merge request with the exact change applied

  8. Slack/Email Alerts — Notify the commit author directly when their commit caused a pipeline failure in another project

  9. Historical Pattern Learning — Build failure pattern database so agent gets smarter over time

Built With

  • custom-agent-skills
  • gitlab-ci-cd
  • gitlab-duo-agent-platform
  • gitlab-orbit-knowledge-graph
  • markdown
  • python
  • yaml
Share this project:

Updates