index

GitLab Ultimate Agent Platform Integration

Last Updated: January 7, 2026 Status: Comprehensive Research Complete Scope: GitLab Ultimate features, GitLab Duo Agent Platform, foundational agents/flows, agent interoperability

Overview

This guide provides comprehensive coverage of GitLab Ultimate's AI agent capabilities and integration patterns with the Agent Platform ecosystem. GitLab Duo Agent Platform (GA January 2026 with GitLab 18.8) enables custom agents and workflows natively within GitLab, complemented by foundational agents built and supported by GitLab.

Key Components

Foundational Agents & Flows - Production-ready agents and workflows by GitLab
Agent Interoperability - OSSA, MCP, A2A protocol integration
Drupal Integration - Drupal as agent marketplace and registry
Commercial Frameworks - Claude Code, OpenAI Agents SDK, Cursor IDE
CI/CD Patterns - Components, Steps, ML/MLOps, security
Platform Agents Analysis - platform-agents repository integration

Quick Links

GitLab Duo Agent Platform

Foundational Agents: Planner, Security Analyst (Ultimate only), Data Analyst
Foundational Flows: Software Development, Developer (Issue to MR), Code Review, CI/CD Conversion
Custom Agents: Maintainer role required, private/public visibility options
External Agents: Third-party AI model integrations (Anthropic, OpenAI, Amazon Q, Google Gemini)
AI Catalog: Central discovery for agents and flows with semantic versioning

GitLab Ultimate Features

Distributed Tracing: OpenTelemetry integration, Monitor Tracing
Error Tracking: Automatic aggregation, Monitor Error Tracking
Performance Monitoring: Dashboards for latency, throughput, token usage, cost attribution
DORA Metrics: Deployment frequency, lead time, MTTR, change failure rate
Value Stream Analytics: End-to-end visibility, bottleneck identification
Security Scanning: SAST, DAST, Dependency Scanning, Secret Detection
Compliance Frameworks: SOC2, FedRAMP, NIST for gov_compliance module

Agent Interoperability

OSSA (Open Standard Agents): Vendor-neutral agent specification, bi-directional conversion with GitLab Duo
MCP (Model Context Protocol): GitLab as both MCP server (exposes data) and client (connects to external servers)
A2A (Agent-to-Agent): Linux Foundation standard for secure inter-agent communication
kagent: CNCF sandbox project for Kubernetes-native agent deployment

Architecture Overview


                    GitLab Ultimate                           
                                                              
      
           GitLab Duo Agent Platform                       
              
     Foundational       Custom      External       
        Agents          Agents       Agents        
              
      
                                                              
      
                MCP Server/Client                          
    (Exposes GitLab data, connects to external tools)     
      
                                                              
      
            GitLab CI/CD + Observability                   
    (Components, Steps, OIDC, Tracing, DORA Metrics)      
      

                          
          
                                        
           
        OSSA        Drupal       Claude  
       Agents       Market       Cursor

Getting Started

Prerequisites

GitLab Version: 18.2 or later (18.8+ recommended for full Agent Platform features)

Licensing:

Premium or Ultimate tier
GitLab Duo Core, Pro, or Enterprise add-on

For Ultimate-Only Features:

Security Analyst Agent
Advanced compliance frameworks
Enhanced observability

Enable Agent Platform

For GitLab.com:

Navigate to: Settings GitLab Duo Change configuration
Select "Turn on GitLab Duo Chat (Agentic), agents, and flows"
Save changes

For Self-Managed:

Navigate to: Admin GitLab Duo Change configuration
Select "Turn on GitLab Duo Chat (Agentic), agents, and flows"
Configure AI gateway and Agent Platform service
Save changes

Enable Foundational Agents

Foundational agents are enabled by default with Agent Platform activation. Access via:

GitLab Duo sidebar in issues, epics, or merge requests
Mention agents in comments: @GitLabDuo, @Planner, @SecurityAnalyst, @DataAnalyst

Integration Patterns

Multi-Protocol Agent Ecosystem

The Agent Platform supports multiple interoperability standards:

OSSA (Open Standard Agents)
   (bi-directional conversion)
GitLab Duo Agent Platform
   (MCP protocol)
Claude Code / Cursor / ChatGPT
   (A2A protocol)
Drupal Agent Marketplace
   (JSON:API / GraphQL)
External AI Agents (OpenAI, Anthropic)

Key Integration Points:

OSSA Integration: platform-agents repository implements bi-directional conversion between OSSA manifests and GitLab Duo format
MCP Integration: GitLab provides both server (exposes data) and client (connects to external tools) capabilities
Drupal Integration: Serves as agent marketplace with JSON:API discovery and MCP server/client
Commercial Frameworks: Claude Code for GitLab CI/CD, OpenAI Agents SDK, Cursor IDE with MCP bridge

Workflow Patterns

Development Workflow:

1. Developer creates issue in GitLab
2. GitLab Duo Developer Flow: Issue  MR (automatic implementation)
3. GitLab CI/CD runs security scans (SAST, dependency scanning)
4. GitLab Duo Code Review Flow provides agentic review
5. Developer addresses feedback
6. GitLab Duo Security Analyst Agent validates fixes
7. Merge to release branch
8. CI/CD deploys with observability enabled
9. GitLab Ultimate tracks DORA metrics

Agent Orchestration:

Cursor Agent (local IDE)
   Implements feature
   Commits to branch
   Creates GitLab MR via MCP
     GitLab Duo Agents (platform)
       Security Analyst: Vulnerability scan
       Planner Agent: Impact analysis
       Code Review Flow: Agentic review
     GitLab CI/CD
       SAST, DAST, dependency scanning
       Deploy to staging
       Run integration tests
     GitLab Ultimate Observability
       Distributed tracing
       Error tracking
       DORA metrics

Cost Management

GitLab Ultimate + Duo Pricing

Per User/Month (2026):

GitLab Ultimate: $99/user/month
GitLab Duo Pro add-on: $19/user/month
Total: $118/user/month for comprehensive AI-powered DevSecOps

Example Team (10 developers):

Ultimate: $990/month
Duo Pro: $190/month
Total: $1,180/month

Adding Commercial Frameworks

Cursor (optional, for IDE-native coding):

Pro: $20/user/month (~225 Sonnet 4 requests)
Pro Plus: $60/user/month (~675 Sonnet 4 requests)
Ultra: $200/user/month (~4,500 Sonnet 4 requests)

Combined Example (10 developers):

GitLab Ultimate + Duo: $1,180/month
Cursor Ultra (10 users): $2,000/month + $500 overages = $2,500/month
Total: $3,680/month

ROI Justification:

Typical 30-40% productivity gain
Equivalent to 3-4 additional developer weeks/month
Reduced security vulnerabilities and compliance violations
Faster time to market

Best Practices

GitLab Ultimate Feature Utilization

"USE EVERYTHING" from CLAUDE.md:

Observability & Monitoring
- Enable OpenTelemetry in CI/CD
- Track all agent executions with distributed tracing
- Monitor service dependencies
- Set up error tracking with alerts (error rate > 5%)
- Create performance dashboards (latency, throughput, token usage, cost)
Security & Compliance
- Run SAST on every MR
- Enable dependency scanning
- Use secret detection to prevent credential leaks
- Implement compliance frameworks (SOC2, FedRAMP, NIST)
- Track audit events for all agent actions
DORA Metrics
- Track deployment frequency
- Measure lead time for changes
- Monitor mean time to recovery (MTTR)
- Analyze change failure rate
- Optimize based on trends
Value Stream Analytics
- End-to-end visibility from issue to production
- Identify bottlenecks in workflows
- Optimize cycle time
- Track team velocity
CI/CD Advanced Features
- Use OIDC authentication (no long-lived tokens)
- Implement CI/CD Components for reusable agent pipelines
- Leverage CI/CD Steps for fine-grained agent orchestration
- Use merge trains for automatic merge queuing
- Deploy with GitLab Agent for Kubernetes (GitOps)

Agent Development Best Practices

Start with Foundational Agents: Use built-in agents before creating custom ones
Clear System Prompts: Define personality, expertise, and behavior explicitly
Tool Selection: Only grant necessary tool permissions
Visibility Management: Use private visibility for experimental agents
Version Control: Leverage AI Catalog versioning for stability
Security First: Implement OIDC, secret detection, approval rules
Observability: Track agent performance, accuracy, cost

Team Collaboration

Shared MCP Configurations: Define team-wide MCP servers in Cursor dashboard
Custom Commands: Create /review-mr, /fix-ci, /add-tests shortcuts
Workspace Settings: Configure default models, repositories, user restrictions
Service Accounts: Use service accounts for CI/CD automation (not personal tokens)
Training: Conduct team training on Cursor agents + GitLab workflows

Documentation Structure

This comprehensive research is organized into the following guides:

1. [object Object]

Planner Agent (product management, prioritization)
Security Analyst Agent (Ultimate only - vulnerability assessment)
Data Analyst Agent (GLQL queries, platform data)
Software Development Flow (VS Code, Visual Studio, JetBrains)
Developer Flow (Issue MR automation)
Code Review Flow (agentic reviews)
CI/CD Conversion Flow (Jenkins migration)

2. [object Object]

OSSA (Open Standard Agents) specification
MCP (Model Context Protocol) server/client
A2A (Agent-to-Agent) secure communication
kagent (Kubernetes-native agents)
Multi-protocol implementation guide
GitLab integration patterns

3. [object Object]

Drupal 11 AI module ecosystem (48+ providers)
AI Agents framework (text-to-action agents)
MCP Server/Client implementation
Vector DB integration (Milvus, Qdrant, pgvector)
Canvas AI (Experience Builder)
Agent registry architecture
JSON:API discovery patterns

4. [object Object]

Claude Code for GitLab CI/CD (OIDC, AWS Bedrock, GCP Vertex AI)
OpenAI Agents SDK integration
GitLab Duo Agent Platform (custom agents, external agents)
Observability & monitoring (LangFuse, Helicone, OpenTelemetry)
Cost management & token tracking
Security best practices

5. [object Object]

CI/CD Components for reusable agent deployments
CI/CD Steps (Functions) for agent orchestration
Merge request integration patterns
ML/MLOps (experiment tracking, model registry)
OIDC authentication for cloud providers
Security scanning (SAST, DAST, dependency scanning)
Pipeline efficiency and caching strategies

6. [object Object]

16 canonical agents (GitLab, Orchestration, Validation, Security, etc.)
OSSA manifest standard (v0.3.2)
Bi-directional GitLab Duo conversion
CI/CD integration patterns
Multi-platform converter architecture (14 converters)
Production-ready agent implementations

7. [object Object]

Cloud Agents (autonomous coding in Ubuntu VMs)
MCP integration for GitLab data access
Team collaboration patterns
GitLab CI/CD integration
Cost management
Complementary workflow with GitLab Duo

Quick Start: Your First Agent

Option 1: Use Foundational Agent

# In a GitLab issue or MR, mention the agent
@GitLabDuo review this merge request for security issues

# Or use specific agents
@Planner analyze this epic and suggest prioritization
@SecurityAnalyst scan this codebase for vulnerabilities
@DataAnalyst show me merge request metrics for this month

Option 2: Create Custom Agent

Navigate to Settings AI Custom Agents
Provide display name: "API Security Reviewer"

Define system prompt:

You are an API security specialist.

Review API endpoints for:
- Authentication/authorization vulnerabilities
- Input validation issues
- SQL injection risks
- XSS vulnerabilities
- Rate limiting implementation

Provide severity levels and concrete fixes.

Select tools: create_issue, query_gitlab_api, run_gitlab_cli
Set visibility: Private (for testing) or Public (for team-wide use)
Save and enable in your project

Option 3: Integrate External Agent

Create .gitlab/duo/flows/claude-code-review.yaml:

name: claude-code-review
agent:
  type: external
  provider: anthropic
  model: claude-sonnet-4-5
triggers:
  - type: mention
  - type: assign
config:
  injectGatewayToken: true
  permissions:
    - read_code
    - write_comment
  systemPrompt: |
    Review code for security, performance, and best practices.
    Focus on OWASP Top 10 vulnerabilities.

Option 4: Deploy via CI/CD

Add to .gitlab-ci.yml:

agent-code-review:
  stage: review
  image: node:24-alpine3.21
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  before_script:
    - apk add --no-cache git curl
    - npm install -g @anthropic-ai/claude-code
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "Review this MR and implement the requested changes"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"

Troubleshooting

Common Issues

Issue: Foundational agents not available

Solution: Ensure Agent Platform is enabled in Settings GitLab Duo
Check: Premium/Ultimate tier with Duo add-on active
Verify: Beta features enabled in group/project settings

Issue: Custom agent can't access GitLab API

Solution: Verify tool permissions include necessary API access
Check: Agent has api or read_api scope
Verify: User has sufficient project permissions

Issue: MCP server connection fails

Solution: Validate MCP server URL and authentication
Check: OAuth 2.0 tokens are not expired
Verify: Network connectivity to MCP server endpoint

Issue: High agent costs

Solution: Implement semantic caching (Helicone)
Check: Use appropriate models (smaller for simple tasks)
Verify: Token limits are set correctly
Monitor: Review usage dashboard for optimization opportunities

Issue: CI/CD agent fails with OIDC error

Solution: Verify id_tokens configuration in .gitlab-ci.yml
Check: OIDC trust policy on cloud provider side
Verify: Audience claim matches expected value

Additional Resources

Official Documentation

Community Resources

Internal Platform Resources

Contributing

To contribute improvements to this documentation:

Create an issue describing the gap or improvement
GitLab will create a branch automatically
Edit wiki pages in the branch
Create MR targeting appropriate release branch
Request review from tech lead

Documentation Standards:

Use clear, concise language
Provide code examples for all patterns
Include troubleshooting sections
Link to official documentation
Cite sources at the end of each guide

Changelog

2026-01-07: Initial comprehensive research completed

GitLab Duo Agent Platform foundational agents & flows
Agent interoperability standards (OSSA, MCP, A2A, kagent)
Drupal agent marketplace architecture
Commercial frameworks integration (Claude, OpenAI, Cursor)
CI/CD agent patterns with GitLab Ultimate features
platform-agents repository analysis
Observability and cost management strategies

Next Updates:

Implementation examples for each integration pattern
Production deployment case studies
Performance benchmarks and optimization guides
Security audit results and recommendations