GitLab Duo Agent Platform: A Practitioner’s Guide to Agents, Flows, Governance and Cost

On September 22, 2026, GitLab engineering published how its Flow Registry cut the code needed per agentic flow by 45%. It is a good read about framework design. It also matters to anyone running GitLab, because the YAML format GitLab uses to build its own flows is the same one your teams use to write custom flows.

We have mentioned GitLab Duo and the Duo Agent Platform in several places on this site without going into detail. This guide fills that gap. It explains what the platform is as of GitLab 19.4, how agents and flows actually execute, how access is controlled, what drives cost, and how we recommend rolling it out. Every product fact below links to GitLab’s own documentation, so you can check it against your version.

What is GitLab Duo Agent Platform?

GitLab describes the Duo Agent Platform as an AI-native way to put multiple specialised agents to work across the lifecycle. Developers hand off routine work such as refactoring, security triage, pipeline repair and research, and collaborate with agents asynchronously rather than prompting one assistant at a time.

The platform is built from two parts:

• Agents. AI assistants that complete a specific task or answer questions using a defined set of tools.
• Flows. One or more agents combined into a multi-step workflow that can be started by hand or by a GitLab event.

How the platform reached general availability

Agents: foundational, custom and external

GitLab supports three kinds of agents:

• Foundational agents are built and maintained by GitLab and are on by default in GitLab Duo Chat. Examples include the Planner Agent and Data Analyst Agent, available on all tiers, and the Security Analyst Agent on Ultimate.
• Custom agents are ones your team defines, with a system prompt and a chosen set of tools. You enable one in a group or project to use it in Chat.
• External agents connect third-party AI model providers so they can work inside GitLab. You mention the agent in an issue, epic or merge request, and it responds with a ready-to-merge change or a comment after running in a CI/CD pipeline.

External agents need more scrutiny than the others. GitLab’s external agents documentation states that GitLab’s prompt-injection scanning is not applied to them. Security controls become the provider’s responsibility, data goes to the provider’s network, and isolation is weaker than for GitLab’s native agents. External agents are also not available with GitLab Duo Self-Hosted models, and GitLab support has to enable them for your namespace or instance. We treat them as a separate risk review, not as a setting to switch on.

Flows: GitLab’s foundational flows, by tier

A flow combines agents to finish a multi-step job. Foundational flows are built and maintained by GitLab. Custom flows are ones you write. Here is what GitLab provides out of the box, with tier and maturity taken from the Agent Platform feature table:

Scroll sideways to see every column.

* Free (with purchased GitLab Credits), Premium and Ultimate.

Two things surprise teams on first use. First, flows started in the GitLab UI run in GitLab CI/CD, and flows started in an IDE run locally. Second, turning a foundational flow off for a group stops it running in GitLab, but developers can still run it from an IDE or the GitLab Duo CLI if the platform is available for that project (foundational flows). Governance needs to cover both places.

Why the 45% Flow Registry result matters to your team

GitLab’s engineering post explains that the platform was first built directly on LangGraph, LangChain’s low-level agent orchestration framework. Each early flow was an ad-hoc graph of at least 450 lines of Python, and platform-wide changes became hard to make. The Flow Registry replaced those graphs with YAML declarations built on three pillars:

• Components, such as agents, human-in-the-loop checkpoints and deterministic tool steps.
• Routers, which connect components and branch on a component’s output.
• A shared state structure that components read from and write to under fixed conventions.

The benefit for customers is direct. Custom flows use the Flow Registry v1 specification, the same YAML format GitLab uses for its own flows, with some restrictions. When GitLab improves a component, flows built on it get the improvement without being rewritten. GitLab’s post also gives a cost reason to split work across agents: a small, cheap model can make a triage decision before an expensive one is used. That matters when every run consumes credits.

What a custom flow looks like

Below is a minimal custom flow we wrote against the v1 specification. Attach it to an Assign reviewer trigger and it reads the merge request, then posts a release-readiness note. With the Assign reviewer trigger, context:goal contains the merge request IID.

version: "v1"
environment: ambient
coding_environment: none   # API-only, no clone
components:
  - name: "release_readiness"
    type: AgentComponent
    prompt_id: "release_readiness_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "mr_iid"
    toolset:
      - "get_merge_request"
      - "create_merge_request_note"
prompts:
  - prompt_id: "release_readiness_prompt"
    name: "Release readiness reviewer"
    unit_primitives: []
    prompt_template:
      system: |
        You review merge requests for release readiness.
        Check for a linked issue, a changelog entry and a
        rollback note. Reply with one short comment that
        lists anything missing.
      user: "Review MR {{mr_iid}} in project {{project_id}}."
    params:
      timeout: 180
routers:
  - from: "release_readiness"
    to: "end"
flow:
  entry_point: "release_readiness"

Custom flows have some limits you should know about. The only allowed environment is ambient. A prompt cannot choose its own model, because the model comes from your group or instance settings. The name, description and product_group fields are rejected (restricted fields). Since GitLab 19.3 you can also build flows visually with the GitLab flow builder in VS Code. It is a beta extension setting.

A flow can be started by triggers, including a mention, an assignment, assignment as a reviewer, pipeline events, merge request events (created, marked ready, approved, merge conflict) and work item events (created, status changed). Several of these were added in GitLab 19.x, so check what your version supports.

How a flow actually runs, and what your runners need

This is the part most teams underestimate. When a flow runs in CI/CD, the runner downloads the GitLab Duo CLI binary, which connects to the GitLab Duo Workflow Service. The runner then executes file operations and Git commands as the model directs (flow execution). In practice, that means:

• You need runners. Configure your own, or turn on GitLab-hosted runners for the project.
• Push rules must allow the flow’s service account, or flows cannot push their work.
• Add .gitlab/duo/agent-config.yml so flows have your toolchain and dependencies. The file is read only from the default branch, and files on other branches are ignored.
• Treat setup_script as privileged. GitLab documents that setup commands run before the sandbox is applied and can see every environment variable in the flow, including the triggering user’s OAuth token. Review changes to this file as carefully as changes to your CI configuration.
• Air-gapped and regulated Self-Managed instances can point foundational flows at their own container registry for the flow images (foundational flows).

Running flows appear under AI > Sessions in the project. That is where you monitor them in the UI.

Security and governance: composite identity and tool approval

Composite identity

Security reviewers usually ask about composite identity first. When you enable a flow in a project, GitLab creates a service account in the top-level group and adds it to the project with the Developer role. Each run uses a one-time token that combines the service account with the person who started the run:

• The most restrictive role wins. If a Maintainer triggers a flow whose service account is a Developer, the flow acts as a Developer.
• A flow can only reach projects that both identities can access.
• Tokens are narrowly scoped. The OAuth token is limited to the ai_workflows and mcp scopes, and CI job tokens are further restricted by job token permissions.
• Merge requests are attributed to the person who started the flow, not to the service account. GitLab does this to support segregation of duties under SOC 2, SOX, ISO 27001 and FedRAMP, so that nobody can prompt a change and then approve it themselves.

Composite identity applies to foundational flows, custom flows and external agents running on runners. It does not apply to Agentic Chat in the UI or IDE.

Agent tool governance

Agent tool governance was added as a beta in GitLab 19.1. It classifies every agent tool as Read, Write or Delete, and administrators set each tool to Always Allow, Always Ask or Always Deny. A denied tool is hidden from the agent entirely. Governance applies to Agentic Chat and IDE extensions. Enforcement for background flows such as the Developer flow was added in 19.3 behind a feature flag that is off by default, so confirm it is on before you rely on it.

Two further beta features give you an audit trail: the AI audit event report (Premium and Ultimate) and the AI Governance Dashboard (Ultimate). Neither consumes credits while in beta.

Giving agents context: AGENTS.md and MCP

GitLab Duo supports the open AGENTS.md convention for repository structure, coding conventions, and build and test instructions. Project-level files are read in the GitLab UI, in editor extensions and in the GitLab Duo CLI. User-level and subdirectory-level files apply only locally. Foundational and custom flows use AGENTS.md, except Code Review Flow. Other AI tools that support the convention read the same file, so you maintain your conventions in one place.

For external context, GitLab Duo Agentic Chat and the Software Development Flow can act as MCP clients. One MCP configuration file works across VS Code, JetBrains IDEs and the GitLab Duo CLI. Connecting custom agents to external MCP servers is a separate beta feature for Premium and Ultimate.

On models, every feature has a default set by GitLab’s AI Gateway. Defaults can change whatever GitLab version you run, and administrators can choose a different supported model for many features (Agent Platform AI models). Record which model each feature uses, because the model affects both output quality and credit consumption.

What it costs: GitLab Credits in practice

GitLab Credits are GitLab’s usage-based billing currency for the Agent Platform. The documented mechanics:

• Billing is consolidated at the top-level group, not by project.
• Included credits come with each Premium or Ultimate user. They cannot be shared, reset monthly and do not roll over.
• Usage order: each user’s included credits are used first, then temporary evaluation credits, then the shared Monthly Commitment Pool, then On-Demand credits at the $1 per credit list price.
• Non-human subjects, such as a service account or bot running an automated flow, receive no included credits. Their usage comes straight from the pool or On-Demand.
• Accepting the usage billing terms turns on On-Demand billing for the rest of the subscription, and you cannot opt out afterwards.
• Beta features that are free today may start billing at general availability, on every version and offering.
• The GitLab Duo Pro and Enterprise add-ons are not usage-billed and do not consume credits.

The practical risk is automation. A flow triggered by every pipeline failure or every new merge request can run hundreds of times a day, and those runs may not draw on anyone’s included credits. Set usage caps in the credits dashboard before you connect a flow to a high-volume trigger. Pilot it on a single group and measure consumption, and use the router pattern described above so that cheap decisions are made by cheap models.

For current list prices and included-credit amounts, see GitLab pricing, our GitLab Duo cost overview and our GitLab licensing comparison.

Self-Managed and self-hosted models

• The Agent Platform is generally available on Self-Managed and Dedicated as well as GitLab.com.
• GitLab Duo Self-Hosted requires the AI Gateway installed with the Agent Platform service (prerequisites).
• With self-hosted models, MCP works in IDEs, the CLI and flows, but not in Agentic Chat in the web UI. External agents are not available.
• On Self-Managed, foundational flows can be switched on or off for the instance, each group and each project. Top-level groups can also choose which individual flows are allowed (foundational flows).

A rollout sequence we recommend

This is ReleaseTEAM’s recommendation rather than GitLab documentation. It is the order that avoids the usual surprises:

1. Take inventory. Record your GitLab version, tier, offering, any Duo Pro or Enterprise add-on, and whether you plan to use self-hosted models. Those five facts determine which rows of the tables above apply to you.
2. Decide on billing before usage starts. Size a Monthly Commitment Pool, set usage caps, and decide deliberately whether to accept On-Demand terms.
3. Prepare the execution path. Set up runners, allow the service account in push rules, and commit .gitlab/duo/agent-config.yml to the default branch.
4. Write AGENTS.md for your most active repositories.
5. Set governance first. Start Write and Delete tools at Always Ask, turn on the AI audit event report, and switch on background-flow enforcement where your version supports it.
6. Pilot two flows on one group. Code Review and Fix CI/CD Pipeline have well-bounded output and are easy to measure.
7. Add custom flows once the baseline is stable. Keep flow YAML in Git and review it in merge requests like any other code.
8. Use Convert to GitLab CI/CD for Jenkins migrations, with human review of every converted pipeline.

Related: GitLab licensing and solutions · GitLab Duo AI tools · GitLab consulting and support

Sources

All product facts in this article come from GitLab. Versions and tiers change with each monthly release, so check the page for your version.

• GitLab Blog: How GitLab reduced code-per-agentic-flow ratio by 45% (September 22, 2026)
• GitLab press release: GitLab Announces the General Availability of GitLab Duo Agent Platform (January 15, 2026)
• GitLab Docs: GitLab Duo Agent Platform
• GitLab Docs: Agents and External agents
• GitLab Docs: Flows, Foundational flows, Custom flows and Custom flow YAML schema
• GitLab Docs: Configure flow execution and Triggers
• GitLab Docs: Composite identity and Agent tool governance
• GitLab Docs: AGENTS.md customization files, GitLab MCP clients and Agent Platform AI models
• GitLab Docs: GitLab Credits and usage billing
• GitLab: Flow Registry v1 specification

Verified against GitLab documentation for GitLab 19.4, September 2026.