Skip to main content

README

GitLab Duo Agent Platform - Complete Documentation

Overview

This directory contains comprehensive technical documentation for the GitLab Duo Agent Platform, the AI-powered orchestration system that enables autonomous agent workflows across the entire software development lifecycle.

Platform Status: Public Beta (December 2025), General Availability January 2026 (GitLab 18.8)

Documentation Structure

[object Object]

Start here for an introduction to the GitLab Duo Agent Platform.

Topics covered:

  • What is the Agent Platform?
  • Core concepts: Agents, Triggers, Flows, Actions
  • Service accounts and composite identity
  • Platform availability and roadmap
  • Key benefits and use cases
  • Integration points

Read this if you:

  • Are new to the Agent Platform
  • Want to understand core concepts
  • Need a high-level overview for stakeholders
  • Are evaluating the platform for your organization

[object Object]

Deep dive into the technical architecture and components.

Topics covered:

  • Architectural layers (Orchestration, Knowledge & Context, Core Platform)
  • Core components (AI Gateway, Duo Workflow Service, GitLab Runner, Knowledge Graph)
  • Communication patterns and data flow
  • Authentication & authorization (OIDC, service accounts, composite identity)
  • Scalability and performance
  • Observability and monitoring
  • Security architecture and threat model
  • Deployment models (SaaS, self-managed, hybrid)
  • Extension points (custom agents, MCP servers)

Read this if you:

  • Are implementing the Agent Platform
  • Need to understand system internals
  • Are designing custom agents or flows
  • Require security and compliance details
  • Are planning infrastructure and deployment

[object Object]

Complete guide to trigger configuration and management.

Topics covered:

  • What are triggers?
  • Event types (mention, assign, assign_reviewer)
  • Trigger lifecycle and execution
  • Service accounts and naming conventions
  • Trigger configuration with conditions
  • Advanced patterns (cascading, conditional chains, time-based, event-based)
  • Trigger management and security
  • Rate limiting and abuse prevention
  • Troubleshooting and debugging

Read this if you:

  • Are configuring agent workflows
  • Want to automate agent execution
  • Need to control when flows run
  • Are implementing security and governance
  • Are troubleshooting trigger issues

[object Object]

Comprehensive guide to flow orchestration and workflow automation.

Topics covered:

  • What are flows?
  • Flow types (foundational vs custom)
  • Flow definition structure (YAML)
  • Step configuration (inputs, outputs, conditions, timeouts, retry logic)
  • Parallel and sequential execution
  • Context and data flow between steps
  • Flow control (conditionals, loops, early termination)
  • Error handling (step-level, flow-level, recovery strategies)
  • Flow execution modes (immediate, queued, scheduled)
  • Flow versioning and testing
  • Flow management (publishing, lifecycle, discovery)

Read this if you:

  • Are creating custom workflows
  • Need to orchestrate multiple agents
  • Want to automate multi-step processes
  • Are implementing complex business logic
  • Need error handling and recovery patterns

[object Object]

Complete reference for agent capabilities, lifecycle, and management.

Topics covered:

  • Agent architecture and components
  • Foundational agents (Chat, Security Analyst, Code Review, Planning, Deep Research, Product Planning)
  • Agent governance (controlling availability, policy-based control)
  • Custom agents (creation, deployment, configuration)
  • External agents (third-party integrations)
  • Agent lifecycle management (states, versioning, updates, rollback)
  • Agent observability (session tracking, metrics, monitoring)
  • Agent security (permissions, audit logging, sandboxing)

Read this if you:

  • Are using GitLab's foundational agents
  • Want to create custom agents
  • Need to integrate external AI systems
  • Are managing agent deployments
  • Require observability and monitoring
  • Need security and compliance controls

[object Object]

Patterns and practices for integrating agents with GitLab CI/CD pipelines.

Topics covered:

  • Integration architecture
  • Authentication methods (OIDC, CI job tokens, service accounts)
  • Integration patterns (agent-driven testing, automated security, intelligent deployment, post-deployment monitoring, automated dependency updates)
  • Complete pipeline examples
  • Advanced patterns (multi-agent orchestration, dynamic pipeline generation, parallel execution, agent-driven feature flags)
  • Error handling in pipelines
  • Monitoring and debugging
  • Performance optimization

Read this if you:

  • Are integrating agents with CI/CD
  • Want agent-driven pipeline workflows
  • Need automated testing and security
  • Are implementing intelligent deployments
  • Want to optimize pipeline performance

[object Object]

Production-ready patterns for deploying and operating the Agent Platform at scale.

Topics covered:

  • Architecture & design principles
  • Security best practices (authentication, input validation, secrets management, least privilege, audit logging)
  • Performance optimization (caching, parallel execution, lazy loading, resource limits, batch operations)
  • Reliability & resilience (error handling, retry logic, circuit breakers, timeouts, health checks)
  • Cost management (token optimization, caching, smart model selection, cost monitoring)
  • Observability (structured logging, metrics, distributed tracing, alerting)
  • Testing (unit tests, integration tests, canary deployments, shadow mode)
  • Documentation standards
  • Governance and compliance
  • Migration and rollback strategies

Read this if you:

  • Are deploying to production
  • Need security and compliance guidance
  • Want to optimize costs and performance
  • Are implementing monitoring and alerting
  • Need governance and change management
  • Are planning for scale and reliability

Quick Start Guide

1. Learn the Basics

Read overview.md to understand core concepts.

2. Explore Architecture

Review architecture.md for technical details.

3. Configure Triggers

Follow triggers.md to set up workflow automation.

4. Create Flows

Use flows.md to build multi-step workflows.

5. Use or Create Agents

See agents.md for agent capabilities and customization.

6. Integrate with CI/CD

Apply integration.md patterns for pipeline automation.

7. Deploy to Production

Follow best-practices.md for production readiness.

Key Concepts Quick Reference

Agents

AI-powered entities that perform specialized tasks autonomously.

  • Foundational: Pre-built by GitLab (Security Analyst, Code Review, Planning, etc.)
  • Custom: User-created for specific needs
  • External: Third-party AI integrations

Triggers

Determine when a flow or agent action should execute.

  • Mention: @service-account in comments
  • Assign: Assign service account to issue/MR
  • Assign Reviewer: Assign service account as reviewer
  • Schedule: Cron-based execution
  • Event: Pipeline events (success, failure, etc.)

Flows

YAML-defined workflows that orchestrate agents.

  • Define sequence of steps
  • Pass data between steps
  • Handle errors and retries
  • Run in CI/CD or IDE

Actions

Specific tasks agents perform within flows.

  • Code analysis
  • Security scanning
  • Issue creation
  • MR comments
  • Deployment decisions

Service Accounts

Non-human accounts representing agents.

  • Created automatically for flows
  • Naming: ai-<flow>-<group>
  • Developer role by default
  • Composite identity with human user

Knowledge Graph

Semantic understanding of codebases.

  • Entities: files, classes, functions
  • Relationships: calls, imports, inherits
  • Used by agents for context
  • Queryable via MCP

Common Use Cases

1. Automated Code Review

# In MR comment: @duo-developer please review
# Agent analyzes code, checks quality, posts feedback

2. Security Vulnerability Triage

# Automatically triggered on security scan
# Agent assesses risk, prioritizes, suggests fixes

3. Deployment Validation

# Before production deployment
# Agent checks tests, security, performance, docs

4. Test Failure Diagnosis

# When tests fail in CI/CD
# Agent analyzes failures, suggests fixes, creates issues

5. Dependency Updates

# Scheduled weekly
# Agent checks updates, tests, creates MR if safe

Platform Versions

GitLab 18.7 (December 2025) - Public Beta

  • Custom Flows introduced
  • Agent governance and control
  • Model selection for agents
  • Planner Agent with create/edit features
  • Abuse reporting for agents
  • Analytics dashboard

GitLab 18.8 (January 2026) - General Availability

  • Enhanced agent observability
  • Public AI Catalog
  • Extended MCP integrations
  • Production-ready stability
  • Launch Event: February 10, 2026

External Resources

Official GitLab Documentation

GitLab Releases

Technical Deep Dives

Support and Community

Getting Help

Contributing

  • Improvements to documentation welcome
  • Share your agent and flow patterns
  • Report issues and suggest enhancements
  • Participate in Agent Platform community

Document Maintenance

Last Updated: January 2026 GitLab Version: 18.7 (Beta), 18.8 GA (Upcoming) Maintained by: Platform Engineering Team

Document History

DateVersionChanges
2026-01-081.0.0Initial comprehensive documentation release
2025-12-180.9.0Draft for GitLab 18.7 beta

Feedback

Documentation feedback and improvements are welcome. Create an issue or submit a merge request to the technical-docs repository.

Ready to get started? Begin with overview.md to learn the fundamentals of the GitLab Duo Agent Platform.