GitLab Duo Production Guide

Overview & Tiers

GitLab Duo is a suite of AI-native features embedded throughout the GitLab DevSecOps platform. It operates across IDE extensions (VS Code, JetBrains, Visual Studio, Eclipse, Neovim) and the GitLab web UI, providing AI assistance at every stage of the software development lifecycle — from planning and coding through testing, security, and deployment.

GitLab is in the middle of a major billing transition: moving from seat-based Duo Pro/Enterprise add-ons to a usage-based credits system. The Agent Platform (GA since GitLab 18.8, January 2026) runs entirely on credits. This is the single most confusing aspect of Duo today.

Duo tiers

Tier	Price	Requires	Key Features
Duo Core	Included	Premium or Ultimate	Basic AI features (limited chat, code explanation)
Duo Pro	$19/user/mo	Premium or Ultimate	Code Suggestions, Duo Chat, refactoring, test generation, fix code
Duo Enterprise	$39/user/mo	Ultimate only	Everything in Pro + MR summaries, root cause analysis, vulnerability explanation/resolution, AI code review, SDLC analytics
Agent Platform	Credits-based	Ultimate	Agents, Flows, Custom Agents, Custom Flows, Security Analyst Agent
Duo with Amazon Q	Bundled	Ultimate (self-managed, AWS)	Amazon Q agents for code reviews, unit tests, Java modernization

AI models under the hood

Duo uses a mix of models depending on the feature:

Claude Sonnet 4.5 — Duo Chat default (since 18.6)
Claude Haiku 4.5 — Agentic Chat default (since 18.7), subsidized credit tier
Claude Sonnet 4 — Agent Platform, Flows, Code Review
Fireworks Codestral — Code completion (subsidized tier)
Gemini 2.5 Flash — Subsidized tier
Claude Opus 4.5 / 4.6 — Premium credit tier
GPT-5 family — Various tiers (gpt-5, gpt-5-codex, gpt-5-mini, gpt-5.2, gpt-5.3-codex)

Billing transition

Duo Pro and Enterprise seat-based subscriptions still exist and do not consume credits. However, the Agent Platform features (agents, flows, custom agents) are credits-only. GitLab is migrating existing seat-based customers to credit pools. Expect the entire platform to move to credits over time.

Architecture

All Duo AI features route through the AI Gateway — a standalone service that sits between GitLab and the LLM providers. There are three deployment modes depending on your data sovereignty requirements.

Data flow

IDE / Web UI | v GitLab Instance (SaaS or Self-Managed) | | (1) Cloud-connected (default) +-----> GitLab Cloud AI Gateway -----> Anthropic / Fireworks / Google / OpenAI | (6 regions globally) | | (2) Self-hosted +-----> Self-hosted AI Gateway ------> Self-hosted LLMs (vLLM / Bedrock / Azure) | (your infrastructure) No data leaves your network | | (3) Hybrid +-----> Self-hosted AI Gateway ------> Some features local, some via GitLab cloud

Code Suggestions fast path

Code completion/generation take a direct path to the AI Gateway at cloud.gitlab.com:443, bypassing the GitLab monolith for lower latency. Other features route through the GitLab instance.

AI Gateway regions (SaaS)

Deployed across 6 regions with Cloudflare + GCP load balancing: us-east4, europe-west2, europe-west3, europe-west9, asia-northeast1, asia-northeast3.

Data sovereignty caveat

The cloud AI Gateway does not enforce strict data sovereignty. Requests are not guaranteed to stay in a particular region — LLM processing locations are determined by third-party providers (Anthropic, Google, etc.). If you need data to stay in a specific geography, use the self-hosted AI Gateway with your own LLMs.

Duo Chat

Duo Chat has two modes: non-agentic (single-context Q&A) and agentic (autonomous multi-source searching, file editing, command execution). The agentic toggle in the UI switches between them.

Context window & limits

Limit	Value
Input tokens	200,000 (~680K-800K characters)
Output tokens	8,192 (~28,600 characters)
Messages sent to LLM	Last 25 per conversation
Conversation retention	Auto-delete after 30 days inactivity (configurable)

Agentic Chat capabilities

Keyword search across issues, MRs, artifacts (note: keyword-based, not semantic)
Read local project files without manual path specification
Create and edit files in multiple locations
Create commits (in GitLab web UI)
Execute git commands (read/write in UI)
Execute shell commands (in IDE extensions)
MCP integration for external data sources
Customizable via AGENTS.md and chat-rules.md files

Available everywhere

Since GitLab 18.5, Duo Chat is available on all pages in the GitLab UI, plus the Web IDE, VS Code, JetBrains, Visual Studio, and Eclipse.

Slash commands

/reset — Clear conversation context
/new — Start a new conversation
/refactor — Refactor selected code
/ — List all available commands
Context actions: “Explain selected snippet,” “Fix,” “Generate tests”

Code Suggestions

Code Suggestions has two modes that serve different purposes. It’s the most credit-efficient Duo feature at 50 requests per credit.

Code Completion

Suggests completions for the current line as you type. Auto-triggers with a short delay. Uses Fireworks Codestral model.

Output: 64 tokens max (~256 chars)
Input: 32,000 tokens max (~128K chars)
Latency: typically <1 second
Prioritizes above-cursor content over below

Code Generation

Generates entire methods, functions, or classes from natural language comments. Triggered by pressing Enter after a comment. Uses Claude Sonnet 4.

Output: 2,048 tokens max (~7K chars)
Input: 80,000 tokens max (~320K chars)
Latency: may take 5+ seconds for complex code
Supports multi-file context

Supported IDEs

VS Code — Multi-suggestion navigation (cycle through alternatives)
JetBrains — Streaming suggestions
Visual Studio — Streaming suggestions
Neovim — Via language server
Eclipse

Technical architecture

IDE Extension → AI Gateway (direct at cloud.gitlab.com:443) → LLM → Response. This bypasses the GitLab monolith for lower latency. Self-managed instances can alternatively route through the GitLab instance.

Agent Platform

The Agent Platform is GitLab’s framework for embedding AI agents throughout the SDLC. GA since GitLab 18.8 (January 2026), it runs on Claude Sonnet 4 and consumes credits (not seat-based billing). Agents can be triggered by mentions, assignments, and pipeline events.

Foundational Agents (GA)

GA Planner Agent

Plans, prioritizes, and tracks work. Converts high-level requirements into structured tasks with estimates and dependencies.

GA Security Analyst Agent

Vulnerability triage, risk assessment, false positive detection, compliance management, remediation planning. Understands EPSS scores, CVE data, and reachability analysis. Available in UI, VS Code (6.57.3+), and JetBrains (3.11.1+).

Beta Data Analyst Agent

Analyzes development metrics and project data. Currently in beta and does not consume credits.

Custom Agents (GA)

You can create your own agents with:

Display name and description — What the agent does
System prompt — Personality, expertise, behavioral instructions
Visibility — Public or Private
Tool selection — Choose from 60+ built-in tools (see below)
Created via projects or the AI Catalog

Agent tools (60+ available)

Custom agents can use a rich set of tools to interact with GitLab:

Issues & Epics

create_issue, get_issue, update_issue
list_issues, create_issue_note
create_epic, get_epic, update_epic
list_epics, create_work_item

Merge Requests

create_merge_request, get_merge_request
update_merge_request, list_merge_request_diffs
create_merge_request_note
post_duo_code_review

Code & Repositories

create_commit, get_commit, get_commit_diff
get_repository_file, list_repository_tree
gitlab_blob_search, gitlab_commit_search
semantic_code_search

CI/CD & Security

get_job_logs, get_pipeline_errors
ci_linter, run_tests
list_vulnerabilities, dismiss_vulnerability
create_vulnerability_issue

Search

gitlab_documentation_search
gitlab_graphql (arbitrary GraphQL queries)
gitlab_issue_search, gitlab_merge_request_search
gitlab_user_search, run_glql_query

IDE-Only Tools

create_file_with_contents, edit_file
read_file, read_files, find_files
grep, list_dir, mkdir
run_command, run_git_command

External Agents (GA)

Pre-configured integrations with external AI providers that run as CI/CD pipelines. See External Agents for details.

Flows & Triggers

Flows are multi-step AI workflows that combine agents with GitLab operations. They consume credits and execute as CI/CD jobs. Monitor them via Automate > Sessions in the GitLab UI.

Foundational Flows (GA)

Flow	What it does	Credit rate
Software Development	IDE-based structured development. Creates a plan, gathers context, stages changes. Supports CSS, Go, HTML, Java, JS, Markdown, Python, Ruby, TypeScript	Varies by model
Developer	Converts issues to merge requests. Analyzes requirements, creates draft MR with development plan. (Formerly “Issue to MR”)	Varies by model
Fix CI/CD Pipeline	Diagnoses and fixes pipeline failures. Analyzes logs, MR changes, repo contents, script errors	Varies by model
Convert to GitLab CI/CD	Converts Jenkins pipelines to GitLab CI/CD YAML. Handles stages, env vars, triggers, artifacts, conditionals	Varies by model
Code Review	Analyzes code changes, MR comments, linked issues. Trigger: assign `@GitLabDuo` as reviewer or `/assign_reviewer @GitLabDuo`	4 req/credit
SAST FP Detection	Identifies and filters false positives in SAST scans with confidence scores	1 req/credit
SAST Vuln Resolution	Generates MRs with context-aware code fixes for SAST vulnerabilities	Varies by model

Custom Flows (Beta)

User-created workflows defined in YAML that combine multiple agents. Custom Flows can be triggered by:

Mention — Service account tagged in issue/MR comments
Assign — Service account assigned to issues or MRs
Assign reviewer — Service account set as MR reviewer
Pipeline events — Triggered on pipeline states: created, started, succeeded, failed

Service accounts follow the naming pattern ai-<flow>-<group> and use composite identity authentication to prevent privilege escalation.

How flows execute

Flows execute as GitLab CI/CD jobs. When triggered, GitLab creates a pipeline that runs the flow’s agent logic. This means flows inherit all CI/CD capabilities — artifacts, variables, resource groups — and can be monitored via the standard pipeline UI or the dedicated Automate > Sessions view.

Model Context Protocol (MCP)

GitLab provides both an MCP server (exposing GitLab data to external AI tools) and acts as an MCP client (consuming external MCP servers from within Duo). The MCP server is Beta since GitLab 18.6, available on Premium and Ultimate tiers.

MCP server — connecting AI tools to GitLab

The GitLab MCP server wraps GitLab’s REST/GraphQL APIs into the MCP protocol, allowing external AI assistants to interact with your GitLab instance natively.

Transport methods

HTTP (Recommended)

Direct connection with no dependencies. Endpoint: https://<gitlab>/api/v4/mcp

Auth: OAuth 2.0 Dynamic Client Registration.

Stdio with mcp-remote

Requires Node.js 20+. Uses npx mcp-remote as a bridge for tools that don’t support HTTP transport natively.

MCP server tools (15 tools)

Tool	Description	Since
`create_issue`	Create issues with title, description, assignees, labels, milestone, epic	—
`get_issue`	Get issue details	—
`create_merge_request`	Create MRs with source/target branch, assignees, reviewers, labels	18.5
`get_merge_request`	Get MR details	—
`get_merge_request_commits`	List MR commits (paginated)	—
`get_merge_request_diffs`	Get MR file changes (paginated)	—
`get_merge_request_pipelines`	Get MR pipeline data	—
`get_pipeline_jobs`	Get CI/CD jobs from pipelines (paginated)	—
`manage_pipeline`	List, trigger, retry, cancel pipelines	18.10
`create_workitem_note`	Add comments to work items	18.7
`get_workitem_notes`	Get work item comments (paginated)	18.7
`search`	Instance-wide search (global, group, project scopes)	18.4
`search_labels`	Find labels in projects/groups	18.9
`semantic_code_search`	AI-powered code snippet search	18.7 (beta)
`get_mcp_server_version`	Returns MCP server version info	—

What you can’t do via MCP (yet)

The MCP server currently cannot create groups or projects, manage users/permissions, configure CI/CD variables, manage container registries, or perform admin operations. It’s focused on the developer workflow: issues, MRs, pipelines, code search. For group/project creation, use the REST API directly.

Supported AI tool clients

Cursor, Claude Code (claude mcp add), Claude Desktop, Gemini Code Assist/CLI, GitHub Copilot (VS Code), Continue (VS Code), OpenAI Codex, Zed.

Setup example (Claude Code)

# Add GitLab as an MCP server in Claude Code
claude mcp add gitlab-mcp \
  --transport http \
  --url "https://gitlab.example.com/api/v4/mcp"

# Or with mcp-remote for stdio transport
claude mcp add gitlab-mcp \
  -- npx mcp-remote "https://gitlab.example.com/api/v4/mcp"

GitLab as MCP client

Duo Chat (agentic) and the Software Development Flow can consume external MCP servers. Configure them via:

Workspace config: <workspace>/.gitlab/duo/mcp.json
User config: ~/.gitlab/duo/mcp.json

Supports stdio, HTTP, and SSE protocols. Two-tier tool approval: permanent (in config file) and temporary (per-session prompts).

External MCP Servers for Agents (Beta)

Custom agents can connect to external MCP servers for accessing data outside GitLab. Configurable from the AI Catalog.

MCP vs GitLab API

The MCP server is a wrapper around the REST/GraphQL API. For self-managed instances, all MCP communication stays local — GitLab does not transmit, store, or process any data. The advantage over raw API calls is that AI tools understand MCP natively, so they can discover and use GitLab capabilities without custom prompt engineering.

Credits System

GitLab Credits are the standardized consumption currency for the Agent Platform. They replaced seat-based billing for agentic features (GA in 18.8). This is the most confusing part of Duo — here’s how it actually works.

Three ways to get credits

Method	How it works	Cost
Included credits	Allocated monthly per user. Reset monthly, no rollover	Premium: $12/user/mo, Ultimate: $24/user/mo (promo rates)
Monthly Commitment Pool	Purchased annually, divided into 12 monthly portions. Volume discounts available	Negotiated
On-Demand	Billed after included + committed credits exhaust. Free tier capped at $25K/mo	$1 per credit

Consumption order: Individual included credits → Monthly commitment pool → On-demand.

How many requests per credit?

Credit consumption depends on which model is used. More capable models cost more.

Model tier	Models	Requests/credit
Feature-specific	Code Suggestions	50
Feature-specific	Code Review Flow	4
Feature-specific	SAST FP Detection Flow	1
Subsidized	Claude 3 Haiku, Codestral, Gemini 2.5 Flash, GPT-5-mini, all self-hosted models	8.0
Standard	Claude Haiku 4.5, GPT-5-4-mini	6.7
Premium	GPT-5, GPT-5-codex	3.3
Premium	GPT-5.2, GPT-5.2-codex, GPT-5.3-codex	2.5
Premium	Claude Sonnet 4/4.5/4.6 (≤200K tokens)	2.0
Premium	Claude Opus 4.5, Claude Opus 4.6	1.2
Premium	Claude Sonnet 4/4.5 (>200K tokens)	1.1

Key distinction

Duo Pro and Enterprise seat-based add-ons do NOT consume credits. They remain seat-based at $19 and $39/user/month respectively. Credits are specifically for the Agent Platform features (agents, flows, custom agents/flows). However, GitLab is actively migrating seat-based subscriptions to credit pools — expect this to converge.

Self-hosted credit consumption

Self-hosted models (via your own AI Gateway + LLMs) consume at the subsidized rate of 8.0 requests/credit. Offline-licensed self-managed instances use seat-based billing with the “Duo Agent Platform Self-Hosted” add-on. Online-licensed instances use usage-based billing.

Governance

Usage dashboards — Real-time visibility into credit consumption
Enable/disable by team or project — Granular feature gating
Automated alerts at 50%, 80%, and 100% of committed monthly credits
Sizing calculator — Estimate monthly credit needs based on team size and usage patterns

Self-Managed Deployment

Duo on self-managed GitLab routes AI requests through an AI Gateway. Three deployment modes are available depending on your data sovereignty and air-gap requirements.

Deployment modes

Default Cloud-Connected

Self-managed GitLab connects to GitLab’s cloud AI Gateway, which routes to Anthropic, Fireworks, Google, and OpenAI. Requires internet connectivity. Simplest setup — no additional infrastructure needed.

Full Control Self-Hosted

Deploy your own AI Gateway with your own LLMs (vLLM, AWS Bedrock, Azure OpenAI). Fully air-gapped — no inference data leaves your network. Anonymous billing metadata (instance ID, call count) is still sent to GitLab.

Flexible Hybrid (GA since 18.9)

Self-hosted AI Gateway for some features, GitLab-managed models for others. Lets you keep sensitive code processing on-premises while using cloud models for less sensitive tasks.

Self-hosted feature availability (GA)

17.9+ — Code Suggestions, Duo Chat (non-agentic), Code Explanation, Test Generation, Refactor Code, Fix Code
18.3+ — AI Code Review
18.8+ — Agent Platform (full)

Self-hosted feature availability (Beta)

17.10+ — Root Cause Analysis
18.1.2+ — Vulnerability Explanation, Merge Commit Message Generation, Discussion Summary, Vulnerability Resolution

Security & Privacy

Data handling

Zero-day data retention — Agreements with Anthropic, Fireworks AI, AWS, and Google. Input/output discarded immediately after processing
No training on your code — “GitLab does not train generative AI models.” All vendors prohibited from using customer content for their own purposes
Chat/workflow history — Retained by GitLab for user convenience and anti-abuse. Users can delete their own chats

Prompt caching exception

Anthropic, Fireworks AI, and VertexAI temporarily retain cached prompts for performance. OpenAI prompt caching cannot be disabled; GitLab adds timestamps to invalidate caches. This is an exception to the zero-day retention policy.

Secret detection & redaction

Since GitLab 17.9, Duo uses Gitleaks to automatically detect and remove API keys, credentials, and tokens before sending code to LLMs. Scanning covers:

Code completion context
AI context (repository files sent to chat)
Workflow tool results
Agentic chat input
Git/CLI command logging

Exception

Secret scanning does NOT occur in the web UI chat interface. If you paste sensitive credentials into Duo Chat via the web browser, they will be sent to the LLM provider unredacted. This only applies to web UI chat — IDE extensions do perform secret scanning.

Telemetry

Aggregated, de-identified usage data collected via Snowplow (unique users, instances, prompt lengths, model type, response times, language/editor). Not used for training. Optional enhanced data sharing (full prompt/response text) available as a voluntary opt-in per group since 18.9.1.

Vulnerability & Security Features

Duo includes several AI features specifically for security workflows, available at the Enterprise tier or via Agent Platform credits.

Enterprise Vulnerability Explanation

For any detected vulnerability, provides clear insights into what it is, potential risks with attack examples, and practical solutions with code snippets.

Enterprise Vulnerability Resolution

Automatically creates MR suggestion comments with fixes. Uses multi-shot analysis tracing vulnerable code through function calls. Powered by Claude.

Credits SAST FP Detection Flow

Automatically analyzes SAST findings. Provides confidence scores and explanations of why findings may or may not be true positives. Visual badges in vulnerability reports. 1 request per credit.

Credits Security Analyst Agent

Specialized AI assistant for vulnerability management. Capabilities: triage, risk assessment, false positive detection, compliance management, remediation planning, workflow automation. Understands EPSS scores, CVE data, reachability analysis.

Other AI-powered features

Root Cause Analysis (Enterprise) — Analyzes failing CI/CD pipelines to identify root causes
Merge Request Summary (Enterprise, Beta) — Auto-generates summaries of code changes
Discussion Summary (Enterprise) — Distills lengthy comment threads into key action points
Code Review Summary (Enterprise, Beta) — Compact overview of reviewer comments
Issue Description Generation (Enterprise, Beta) — AI-generated issue descriptions
Merge Commit Generation (Enterprise) — AI-generated merge commit messages
SDLC Trends Analytics (Enterprise) — Value stream forecasting and trends

Adoption Checklist

Before enabling Duo

Determine your tier: Duo Pro ($19/user/mo) vs Duo Enterprise ($39/user/mo) vs credits-only for Agent Platform
For Agent Platform: estimate monthly credit needs using the sizing calculator. Consider included credits ($12 or $24/user/mo) vs commitment pool vs on-demand ($1/credit)
Decide deployment mode: cloud-connected, self-hosted, or hybrid
If self-hosted: provision AI Gateway infrastructure and LLMs (vLLM, Bedrock, or Azure OpenAI)
Review data sovereignty requirements — cloud AI Gateway does NOT guarantee regional data residency
Confirm GitLab version: 18.8+ for full Agent Platform GA; 17.9+ for basic self-hosted Duo

Configuration

Enable Duo at the instance/group/project level as appropriate
Configure AGENTS.md files with team-specific coding standards and preferences
Set up MCP server access if using external AI tools (Claude Code, Cursor, etc.)
Configure external MCP servers in .gitlab/duo/mcp.json if Duo Chat needs external data
Set up credit governance: enable/disable features per team, configure alert thresholds
Install IDE extensions (VS Code, JetBrains, etc.) and configure connection to GitLab instance

Security review

Verify secret detection is enabled (on by default since 17.9)
Understand prompt caching implications (Anthropic, Fireworks, VertexAI temporarily retain cached prompts)
Note: web UI chat does NOT perform secret scanning — educate users accordingly
Review telemetry settings and opt-in/out of enhanced data sharing
For self-hosted: verify AI Gateway logs do not persist sensitive data beyond your retention policy
For Agent Platform: review composite identity authentication to understand permission scoping

Ongoing operations

Monitor credit consumption dashboards — watch for runaway agentic workflows
Review SAST FP Detection results regularly (1 req/credit — most expensive per-request feature)
Keep IDE extensions updated — new features ship with extension version bumps
Track GitLab release notes — Duo features ship every monthly release (new tools, models, flows)
Update AGENTS.md as team standards evolve

AI Gateway

The routing layer between GitLab and LLM providers

What is the AI Gateway?

The AI Gateway is a standalone service that acts as the intermediary between a GitLab instance and AI model providers. Every Duo AI feature routes through the gateway. GitLab operates a multi-region cloud instance, but organizations can deploy their own for data sovereignty.

Cloud AI Gateway

Deployed across 6 GCP regions with Cloudflare load balancing
Regions: us-east4, europe-west2, europe-west3, europe-west9, asia-northeast1, asia-northeast3
Endpoint: cloud.gitlab.com:443
Routes to: Anthropic, Fireworks AI, Google Vertex AI, OpenAI

Self-hosted AI Gateway

Deploy on your own infrastructure
Connect to self-hosted LLMs via vLLM, AWS Bedrock, or Azure OpenAI
Fully air-gapped — inference data never leaves your network
Anonymous billing metadata (instance ID, call count, anonymized user ID) still sent to GitLab
Hybrid mode (GA since 18.9) lets you mix self-hosted and cloud-connected per feature

Data sovereignty caveat

The cloud AI Gateway does not enforce strict data sovereignty. While the gateway itself runs in specific regions, the actual LLM processing happens at third-party provider locations (Anthropic, Google, etc.), which may be in different regions. For guaranteed data residency, use the self-hosted gateway with local LLMs.

AGENTS.md

Customization files that provide context and instructions to Duo

What is AGENTS.md?

AGENTS.md files are Markdown files that provide persistent context and behavioral instructions to GitLab Duo. They function like a “system prompt” for your project, telling Duo about your coding standards, architecture, technology stack, and team preferences. GA since GitLab 18.8.

File locations (checked in order)

User-level: ~/.gitlab/duo/AGENTS.md — Personal preferences that apply across all projects
Workspace root: <repo>/AGENTS.md — Project-wide instructions
Subdirectories: <repo>/packages/api/AGENTS.md — Monorepo support: different instructions per package

What to put in AGENTS.md

Coding preferences — Naming conventions, preferred patterns, linting rules
Architecture guidance — Module structure, layer boundaries, data flow
Tech stack specifics — Frameworks, libraries, versions
Security guidelines — Auth patterns, data handling rules, approved dependencies
Testing standards — Coverage expectations, test framework preferences, mocking approaches

Companion file: chat-rules.md

A chat-rules.md file provides additional instructions specifically for Duo Chat conversations. Both files work together — AGENTS.md for broad context, chat-rules.md for conversational behavior.

Knowledge Graph

Structured graph database of code relationships for deeper AI understanding

What is the Knowledge Graph?

The GitLab Knowledge Graph (Beta) creates a structured graph database from your code repositories. It captures files, directories, classes, functions, modules, and their relationships, giving Duo AI features deeper code understanding beyond simple file reads.

How it works

Parses local repositories and builds a code relationship graph
Captures: files, directories, classes, functions, modules, and interconnections
Connects to Duo via MCP
CLI tool: gkg (installable via one-line script)

Supported languages

Rust, TypeScript, Python, Ruby, and more being added.

Availability

Free, Premium, and Ultimate tiers. Beta status. The graph powers AI features with significantly better code understanding than simple file-at-a-time context.

External Agents

Pre-configured integrations with external AI providers that run as CI/CD pipelines

What are External Agents?

External Agents are pre-built integrations that connect GitLab with external AI coding platforms. They’re GA and trigger when a service account is mentioned in comments, assigned to issues/MRs, or assigned as a reviewer. They execute as CI/CD pipelines and respond with code changes or comments.

Available External Agents

Claude Code Agent (Anthropic) — GitLab-managed credentials. Models: claude-3-haiku, claude-haiku-4-5, claude-sonnet-4, claude-sonnet-4-5
Codex Agent (OpenAI) — Models: gpt-5, gpt-5-codex
Amazon Q Developer Agent — Requires user-provided AWS credentials
Develop with Gemini Agent — Requires user-provided Google Cloud credentials

Trigger methods

Mention — Tag the agent’s service account in a comment
Assign — Assign the service account to an issue or MR
Assign reviewer — Set the service account as an MR reviewer

How it works: When triggered, GitLab creates a CI/CD pipeline that runs the external agent. The agent reads the issue or MR context, interacts with the code, and responds with merge-ready changes or inline review comments. The pipeline artifacts contain the agent’s full execution log.

Composite Identity

Authentication mechanism that prevents AI agents from escalating privileges

What is Composite Identity?

Composite Identity is the authentication mechanism used by Custom Flows and the Agent Platform to prevent privilege escalation. When a flow runs, it creates a “composite” of the triggering user’s permissions and the service account’s permissions, taking the intersection (most restrictive) of both.

Why it matters

Without Composite Identity, an AI agent running as a service account could access resources that the triggering user shouldn’t be able to reach. For example, if a Developer triggers a flow, but the service account has Maintainer access to a sensitive repo, the flow could read or modify code the Developer can’t normally touch.

How it works

Service accounts for flows follow naming: ai-<flow>-<group>
When a user triggers a flow, the system computes the intersection of both identities’ permissions
The flow can only access resources that both the user and the service account can access
This prevents a low-privilege user from leveraging a high-privilege service account

Practical implication: When configuring Custom Flows, the service account needs access to the resources the flow operates on, but the flow will only execute with the triggering user’s level of access. This is a security feature, not a limitation — it ensures AI agents respect your existing RBAC model.