GitLab Atlas — Code to Architecture in One Command

• 

  Atlas flows enabled alongside GitLab's foundational flows — 100% platform-native integration

• 

  Architecture Evidence tab — browse generated docs with confidence scores and trust signals

• 

  Atlas Control Hub — select any project, verify readiness, one-click Bootstrap

• 

  Bootstrap MR with auto-generated Interactions table and PlantUML system architecture diagram

• 

  Drift Report — JSON governance decision with docs_stale detection and recommended actions

• 

  Drift-Check — Changed Components table with Mermaid sequence diagram showing webhook flow

• 

  Atlas Analysis — file-by-file Change Categories with impact levels and Mermaid sequence diagram

• 

  Atlas Bootstrap service account — AI agent that autonomously generates architecture baselines

• 

  Atlas Navigator service account — activity log showing explain and drift-check across multiple MRs

Inspiration

Most GitLab projects have no architecture documentation. New developers spend days reading code just to understand how things connect. AI makes writing code faster than ever — but the docs that make code understandable are still a manual task.

We asked: what if one @mention could generate a complete architecture baseline — and keep it alive forever?

What it does

GitLab Atlas is a closed-loop living architecture system built entirely on GitLab Duo Agent Platform.

• Bootstrap: One @mention scans the entire repo and generates 6 architecture artifacts — tech stack, components, interactions, PlantUML deployment diagrams, Mermaid data flow charts, and a sequence diagram. Everything arrives as a merge request.
• Explain: On any MR, Atlas posts a structured change analysis with file categorization, a Mermaid sequence diagram, and a reviewer focus guide.
• Drift-Check: Atlas compares MR changes against the architecture baseline, classifies drift severity (low/medium/high), and outputs a machine-readable JSON governance decision (allow/warn/require_docs_update/require_follow_up). High-severity drift automatically creates a follow-up issue.
• Refresh: After merge, Atlas detects new components and updates the architecture baseline automatically.

Generate → Govern → Refresh — this loop runs without human intervention.

How we built it

• 3 custom GitLab Duo flows with multi-component architecture (Analyzer → Generator → Validator)
• 2 custom agents (Atlas Cartographer for repo analysis, Atlas Navigator for MR analysis)
• Web Dashboard on Google Cloud Run with GitLab OAuth, 8-point health check, and one-click bootstrap
• PlantUML + Mermaid diagrams rendered natively in GitLab MR descriptions and issue comments
• All tools use the GitLab Duo Agent Platform v1 schema: create_file_with_contents, run_git_command, create_merge_request, list_merge_request_diffs, etc.

Challenges we ran into

• Token exhaustion: Large MR descriptions (7-9K chars) with inline diagrams consumed the LLM's token budget before it could post the issue summary. Solved by splitting into 3 components — Generator handles files+MR, Validator posts the summary.
• Tool parameter hallucination: The LLM kept inventing a repository_url parameter that doesn't exist. Solved with explicit TOOL PARAMETER RULES blocks in prompts.
• Mermaid syntax errors: GitLab's Mermaid 10.7 treats / in labels as parallelogram triggers. Solved by enforcing quoted labels in prompts.
• Service account naming: GitLab Duo creates accounts as @ai-{flow}-{group}, which is less intuitive than @coderabbitai. We documented the pattern clearly and plan to split Navigator into separate explain/drift flows for zero-parameter UX.

Accomplishments we're proud of

• Closed-loop system: No other tool does Generate + Govern + Refresh automatically. Docs that defend themselves.
• 100% platform-native: Zero external API keys. Zero config. Fork, tag, enable — done.
• Machine-readable governance: JSON drift decisions that CI/CD pipelines can consume.
• Tested on real projects: Successfully bootstrapped and governed vibeVoice (Next.js) and openClawOffice (React+Express).

What we learned

• GitLab Duo Agent Platform is powerful but requires careful prompt engineering — especially anti-hallucination guards for tool parameters.
• Multi-component flows (3-component split) dramatically improve reliability vs. single-component.
• context:project_id must be explicitly declared in flow inputs — tools don't auto-inject it.

What's next for GitLab Atlas

• Split Navigator into separate atlas-explain and atlas-drift flows for zero-parameter UX
• Pipeline-event triggers for fully automated post-merge refresh
• Diff-aware refresh that only updates changed sections of ARCHITECTURE.md
• Community flow catalog: let teams publish custom architecture templates

Built With

• docker
• fastapi
• gitlab
• gitlab-ci/cd
• gitlab-duo
• gitlab-duo-agent-platform
• gitlab-oauth
• google-cloud
• google-cloud-run
• mermaid
• platuml
• python