GitLab Guardian Army — AI Multi-Agent DevSecOps System

11 AI agents + 1 auto-flow that guard your entire SDLC — code review, security scanning, debugging, testing, docs & deployment — all coordinated by one BOSS agent. Zero friction. Zero missed bugs.

Comment

Inspiration

Every developer knows the pain. You open GitLab on Monday morning and face:

47 unreviewed merge requests piling up A pipeline failure nobody can explain A security vulnerability that slipped through last week's deploy Documentation that was "last updated 6 months ago" A new team member asking "where do I even start?"

We asked ourselves a simple question:

What if an entire army of AI specialists could handle all of this — automatically, instantly, and without a single thing falling through the cracks?

The military has specialized units — each trained for one mission. A sniper doesn't defuse bombs. A medic doesn't fly helicopters. Every specialist does ONE thing at an elite level. That's the idea behind GitLab Guardian Army — a hierarchical multi-agent AI system where 11 specialist agents and 1 automated flow work together under a single commander to guard the entire software development lifecycle. No more context-switching. No more missed bugs. No more "I'll review it later." The Guardians never sleep. They never forget. They never miss.

What it does

GitLab Guardian Army is a military-grade multi-agent AI system built on the GitLab Duo Agent Platform. It removes friction from every stage of the SDLC — from onboarding a new developer to deploying production code. 🏗️ Architecture — The Chain of Command

Copy to clipboard Insert at cursor ┌─────────────────────────────────────────────┐ │ 👑 BOSS │ │ Supreme Commander │ │ (Only agent that talks to the user) │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ 🛡️ BUDDY │ │ Guardian of Guardians │ │ (Monitors all agents in real time) │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ SPECIALIST ARMY │ │ │ │ 🎯 ONBOARD 🔍 CODE 🔒 SECURITY │ │ 🐛 DEBUG 📝 DOCS 🧪 TEST │ │ 🚀 DEPLOY 🤝 TEAM 📊 REPORT │ └─────────────────────────────────────────────┘

🤖 The 11 Agents

Agent Role What It Does

👑 BOSS Supreme Commander Receives user requests, deploys the right specialists, compiles final reports

🛡️ BUDDY Guardian of Guardians Monitors all agents in real time, self-heals failures silently

🎯 ONBOARD First Contact Specialist Detects new users, sets up projects, makes GitLab feel like home in minutes

🔍 CODE Code Review Specialist Military-grade code review — syntax, logic, performance, security, style

🔒 SECURITY Security Sentinel Scans for vulnerabilities, hardcoded secrets, injection attacks, auth flaws

🐛 DEBUG Error Eliminator Finds pipeline failures, traces root cause, applies surgical fixes

📝 DOCS Documentation Master Reads your code, writes perfect docs — README, API docs, inline comments, guides

🧪 TEST Quality Assurance Writes comprehensive tests, runs them, fixes failures, targets 100% coverage

🚀 DEPLOY Deployment Specialist Zero-downtime deployments with automatic rollback if anything breaks

🤝 TEAM Team Coordinator Assigns tasks, balances workload, flags blockers, keeps everyone on track

📊 REPORT Intelligence Specialist Collects data from all agents, finds patterns, delivers clean project insights

⚡ The Guardian Auto Flow The Guardian Auto Flow triggers automatically on every merge request — zero human input required:

Copy to clipboard Insert at cursor MR Opened / Updated ↓ 🔍 CODE Agent → Reviews all changed files ↓ 🔒 SECURITY Agent → Scans for vulnerabilities ↓ 👑 BOSS Agent → Compiles final report ↓ 📝 Report posted as MR comment ↓ DONE

Every MR gets an instant code review + security scan + compiled report — before any human even looks at it. 🧠 Smart User Detection The BOSS agent automatically detects the user's skill level and adapts:

User Type Communication Style

Beginner Simple, friendly, step-by-step guidance

Developer Technical, precise, code-level detail

Team Lead Metrics, reports, strategic insights

How we built it

Phase 1 — Design the Command Structure We started with the core principle: one agent, one job, zero overlap. We mapped every pain point in the SDLC to a specialist: $$\text{Total Coverage} = \sum_{i=1}^{11} \text{Agent}_i(\text{specialty}) = \text{Full SDLC}$$ Each agent was designed with:

A classification protocol (e.g., ULTRA - CODE REVIEW PROTOCOL) A strict identity — who it is and what it does A step-by-step protocol — exactly how it operates A structured output format — consistent, parseable results Hard rules — what it must NEVER do

Phase 2 — Build the Agent Army All 11 agents were built as GitLab Duo Agent Platform YAML configurations:

Copy to clipboard Insert at cursor name: "GitLab Guardian - BOSS" description: "Supreme Commander..." public: true system_prompt: | # CLASSIFICATION: ULTRA - MILITARY GRADE AI COMMANDER ## IDENTITY ## PROTOCOL ## OUTPUT FORMAT tools:

  • read_file

Each agent file lives in the agents/ directory:

Copy to clipboard Insert at cursor agents/ ├── boss-agent.yml # 👑 Supreme Commander ├── buddy-agent.yml # 🛡️ Health Monitor ├── onboard-agent.yml # 🎯 Onboarding ├── code-agent.yml # 🔍 Code Review ├── security-agent.yml # 🔒 Security Scan ├── debug-agent.yml # 🐛 Error Elimination ├── docs-agent.yml # 📝 Documentation ├── test-agent.yml # 🧪 Testing ├── deploy-agent.yml # 🚀 Deployment ├── team-agent.yml # 🤝 Coordination └── report-agent.yml # 📊 Intelligence

Phase 3 — Build the Auto Flow The Guardian Auto Flow was built as a GitLab Duo Flow with 3 chained components:

Copy to clipboard Insert at cursor code_reviewer → security_scanner → boss_commander → end

Each component uses an AgentComponent type with a dedicated inline prompt, connected via routers that define the execution pipeline. Phase 4 — CI/CD Validation Pipeline We built a custom .gitlab-ci.yml pipeline with 3 validation stages:

Agent Validation — Python script checks every agent YAML for required fields (name, description, public, system_prompt, tools) Flow Validation — Validates flow YAML structure and component wiring Project Structure Validation — Ensures README.md, LICENSE, CONTRIBUTING.md, and CHANGELOG.md all exist

Phase 5 — AI Catalog Registration All 11 agents + 1 flow were registered in the GitLab AI Catalog via .ai-catalog-mapping.json, making them publicly discoverable and usable by anyone. Phase 6 — Documentation & Open Source

README.md — Full project documentation with architecture diagrams CONTRIBUTING.md — Contributor guidelines CHANGELOG.md — Complete project history MIT License — Fully open source

Challenges we ran into

  1. 🧩 Agent Boundary Design The hardest challenge was defining clear boundaries between agents. When does a "code review" become a "security scan"? When does "debugging" overlap with "testing"? We solved this by giving each agent a strict classification protocol and hard rules about what it must NEVER do — ensuring zero overlap.
  2. 🔄 Flow Component Chaining Getting the Guardian Auto Flow to correctly chain code_reviewer → security_scanner → boss_commander required careful input/output mapping. Each component's output had to be formatted as the next component's input. We iterated through multiple versions to get the routing and data passing right.
  3. 🎯 Prompt Engineering at Scale Writing system prompts for 11 different agents that are each precise, consistent, and don't contradict each other was a massive prompt engineering challenge. We developed a standard template (Classification → Identity → Protocol → Rules → Output Format) and applied it uniformly across all agents.
  4. 📋 YAML Schema Compliance The GitLab Duo Agent Platform has specific YAML schema requirements. Getting all 11 agent files + 1 flow file to pass CI validation required careful attention to field names, indentation, and structure. Our custom Python validation script in the CI pipeline caught issues early.
  5. 🧠 User Skill Level Detection Making the BOSS agent dynamically adapt its communication style (Beginner vs Developer vs Team Lead) without explicit user input required careful prompt design — the agent had to infer skill level from the user's language, question complexity, and context.

Accomplishments that we're proud of

🏆 By the Numbers

Metric Value

Total AI Agents 11

Automated Flows 1

SDLC Stages Covered 10 (onboarding, code review, security, debugging, docs, testing, deployment, team coordination, reporting, health monitoring)

AI Catalog Registrations 12 (11 agents + 1 flow)

All Agents Public ✅ Yes

CI Pipeline Stages 3 (agent validation, flow validation, structure validation)

Lines of Prompt Engineering 500+ across all agents

Zero Overlap Between Agents ✅ Guaranteed by design

🌟 Key Accomplishments

Full SDLC Coverage — We didn't build one agent. We built an entire army that covers the complete software development lifecycle end-to-end.

Hierarchical Command Structure — The BOSS → BUDDY → Specialists architecture ensures clean coordination, no conflicts, and a single point of contact for the user.

Self-Healing System — The BUDDY agent monitors all other agents in real time. If any agent fails, BUDDY intervenes and fixes it silently — the user never knows there was a problem.

Zero-Touch Auto Flow — The Guardian Flow triggers automatically on every MR. No setup. No commands. No human input. Just instant code review + security scan + compiled report.

Adaptive Intelligence — The BOSS agent detects whether you're a beginner, developer, or team lead — and adjusts its entire communication style accordingly.

Production-Grade Project Structure — README, CONTRIBUTING guide, CHANGELOG, MIT License, CI/CD pipeline, issue templates, MR templates — everything a real open-source project needs.

What we learned

  1. 🧠 Multi-Agent Systems Need Clear Hierarchies Without a clear chain of command, agents conflict with each other. The BOSS → BUDDY → Specialists hierarchy was the single most important design decision. One commander. One monitor. Nine specialists. Zero confusion.
  2. 📐 Prompt Engineering is Architecture Writing prompts for 11 agents isn't creative writing — it's software architecture. Each prompt is a contract that defines inputs, outputs, boundaries, and failure modes. We learned to treat prompts like code: structured, versioned, and tested.
  3. ⚡ Flows Are the Real Power Individual agents are useful. But flows that chain agents together and trigger automatically — that's where the real value is. The Guardian Auto Flow delivers more value than any single agent because it removes the need for human initiation entirely.
  4. 🔒 Boundaries > Features It's tempting to make each agent do everything. But we learned that strict boundaries (what an agent must NEVER do) are more important than capabilities (what it CAN do). Constraints create clarity.
  5. 🏗️ The GitLab Duo Agent Platform is Powerful The platform's YAML-based agent definitions, flow routing, AI Catalog registration, and CI validation pipeline made it possible to build a complex multi-agent system without writing a single line of application code. The entire system is configuration as code.

What's next for GitLab Guardian Army — AI Multi-Agent DevSecOps System

🗺️ Roadmap

Phase Feature Status

v1.0 11 agents + 1 flow (current) ✅ Complete

v1.1 Enhanced tool integration — agents use gitlab_search, create_issue, create_merge_request 🔜 Next

v1.2 Multi-flow pipelines — separate flows for CI/CD, security, and onboarding 📋 Planned

v1.3 Cross-project Guardian deployment — protect multiple repos from one config 📋 Planned

v2.0 Guardian Dashboard — real-time web UI showing all agent activity and project health 🔮 Future

🚀 Immediate Next Steps

Expand Tool Access — Give agents access to more GitLab tools (create_issue, create_merge_request, gitlab_search) so they can take direct action, not just analyze.

Add More Flows — Build dedicated flows for:

🔒 Security Flow — triggers on every commit, not just MRs 🎯 Onboarding Flow — triggers when a new member joins the project 📊 Weekly Report Flow — scheduled flow that delivers project health reports every Monday

Agent Memory — Enable agents to remember context across conversations, so the BOSS agent can say "Last time you asked about security, we found 3 issues — 2 are now fixed."

Community Contributions — The project is open source (MIT License) with a CONTRIBUTING.md guide. We want the community to build new specialist agents and contribute them to the army.

🎯 The Vision

Every GitLab project deserves a Guardian Army.

Today it's 11 agents. Tomorrow it could be 50 — each one a specialist, each one public, each one making developers' lives easier. The goal is simple: developers should focus on building. The Guardians handle everything else.

Built With

  • gitlabaicatalog
  • gitlabci/cd
  • gitlabduoagentplatform
  • gitlabduochat
  • gitlabflows
  • gitlabwebide
  • markdown
  • python
  • yaml
Share this project:

Updates