Developer Flow

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

The Developer Flow helps you work more efficiently across issues and merge requests. You can use the Developer Flow to:

  • Create a draft merge request from an issue.
  • Iterate on an existing merge request based on review feedback.
  • Research implementation approaches and post findings to a discussion.
  • Split a large merge request into smaller, focused merge requests.
  • Resolve merge conflicts.

Prerequisites

To ensure the best results, before you use the Developer Flow for the first time, set up your project. Configure the AGENTS.md and agent-config.yml files to significantly improve the quality and reliability of the Developer Flow’s results.

Set up your project

To help the Developer Flow produce better results, you should configure your project with the following optional settings:

  • Add an AGENTS.md file: Document your project conventions, such as test commands, linting rules, commit format, and coding patterns. The Developer Flow uses this file for context when working in your repository. For more information, see AGENTS.md customization files.
  • Add workspace subagents: Define specialized subagents in the .agents/agents/ directory that the Developer Flow can delegate focused tasks to, like reviews or research. This feature is an experiment. For more information, see workspace subagents.
  • Configure the execution environment: If your project requires specific tooling (for example, Go, Python, or Node.js), configure the agent environment with an agent-config.yml file. Without this, the Developer Flow cannot install dependencies or run tests, and is more likely to produce changes that don’t build or pass. With a properly configured environment, the Developer Flow can run tests and verify its own changes before committing. For more information, see Configure flow execution.
  • Choose a model: The Developer Flow uses the GitLab default model, tuned for a balance of cost and performance. For focused tasks, a faster model reduces iteration time; for complex, multi-step tasks, a more capable model reduces the risk of an incomplete plan. For more information, see GitLab Duo AI models.

Use the flow

Prerequisites:

  • The event types Mention and Assign are configured in the trigger for the Developer Flow.

Mention Duo Developer in a discussion

To turn your comment into an actionable task for the Developer Flow, mention @duo-developer-<namespace> in a comment. Replace <namespace> with your GitLab namespace path (for example, gitlab-org).

Depending on the issue or merge request content and the amount of context you provide, the flow can execute the following tasks:

  • Code changes
  • Merge request and issue creation
  • Research an implementation approach and report back or updates accordingly

For example:

@duo-developer-<namespace> research approaches for implementing pagination
on the /users endpoint, then create a draft MR with the most
promising approach.

The Developer Flow responds with a link to its session.

Alternatively, to monitor progress, in the left sidebar, select AI > Sessions.

Generate a merge request from an issue

To create a merge request from an issue:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Plan > Work items, then filter by Type = Issue.
  3. Select the issue you want to create a merge request for.
  4. To create a merge request from the issue, either:
    • Assign the Duo Developer service account to the issue:
      1. In the right sidebar, in the Assignees section, select Edit.
      2. Type duo developer and select it from the search results.
    • Below the issue header, select Implement.
  5. To monitor progress, in the left sidebar, select AI > Sessions.
  6. When the session completes, review the merge request from the link in the Activity section of the issue.

When you assign the flow to an issue that has a workplan, the flow follows the workplan. If the description and the workplan disagree, the flow follows the workplan.

Start the flow when a work item status changes

When a work item changes to a status that you select, the Developer Flow implements the work item and creates a merge request. The flow uses the workplan of the work item as its specification. If the work item has no workplan, the flow uses the description.

Prerequisites:

  • Create a trigger for the Developer Flow with the Work item event type and only the Status changed action. If you also select Created, you cannot select statuses, and the flow does not start when a work item is created.
  • In the trigger, select the statuses that start the work. If you select no status, every status change starts a session, including a change to a done status.

To start the flow:

  1. Change the status of the work item to one of the statuses selected in the trigger.
  2. To monitor progress, in the left sidebar, select AI > Sessions.
  3. When the session completes, review the merge request from the link in the Activity section of the work item. The flow assigns the merge request to the user who changed the status.

Use the flow in Agentic Chat

You can use the Developer Flow in a GitLab Duo Agentic Chat conversation to complete different tasks, such as:

  • Accomplish a coding goal. You do not need an issue associated with this goal.
  • Resolve an issue by opening a merge request.

To use the flow in an Agentic Chat conversation:

  1. In the top bar, select Search or go to and find your project.

  2. In the GitLab Duo sidebar, open a new or existing Agentic Chat conversation.

  3. Ask Agentic Chat to use the Developer Flow to accomplish a task.

    The flow progress is displayed in the Chat conversation. For more information, you can do the following:

    • Select View Agent Session in the conversation.
    • In the left sidebar, select AI > Sessions.

Provide images as context

The availability of this feature is controlled by a feature flag. For more information, see the history.

Prerequisites:

  • Use a GitLab-managed model. Models that you host yourself are not supported.
  • For a flow that runs in a pipeline, the execution environment must include GitLab Duo CLI 9.29.0 or later. In GitLab 19.5.0, the default execution image does not meet this requirement. GitLab 19.5.1 and later do.

The Developer Flow can read images and use them as context for a task. You can provide images when you use the flow in Agentic Chat, in the GitLab Duo CLI, or in a flow started from a discussion or an issue. The flow can read:

  • Image files in the repository.
  • Images attached to an issue, merge request, or comment in the same project.

You cannot upload an image directly in your prompt. Instead, name an image that already exists:

  • For a file in the repository, give the file path. For example, docs/architecture.png.
  • For an attachment, give the upload reference as it appears in the Markdown. For example, /uploads/<secret>/screenshot.png.

When the flow works on an issue, it can also read the images attached to that issue.

Image requirements

To use an image as context, the image must meet the following requirements:

  • Format: PNG, JPEG, or WebP file
  • Size: 10 MB or smaller
  • Dimensions: Not wider or taller than 8,000 pixels

Best practices

Provide clear context

The Developer Flow only knows what you tell it or what is available in the context of the issue, merge request, Chat conversation, or discussion thread. The same practices that help a human collaborator apply here:

  • Write a clear problem description with links to relevant files or discussions.
  • Include acceptance criteria that define what “done” looks like.
  • Specify exact file paths when you know them.
  • Include code examples of existing patterns to maintain consistency.
  • Attach screenshots, diagrams, or mockups to the issue, or commit them to the repository, and name them in your request. For more information, see Provide images as context.

Be explicit when mentioning Duo Developer in discussions

When you mention Duo Developer in a discussion, tell it exactly what you want it to do. For example:

  • “Create a draft merge request that implements pagination for the /api/users endpoint.”
  • “Address the review feedback on this merge request.”
  • “Split the logging changes into a separate merge request.”
  • “Research approaches for migrating this service to gRPC and post your findings here.”
  • “There are merge conflicts on this merge request. Please resolve them.”

Without explicit instructions, the flow chooses its own approach, which might not match your expectations.

Keep tasks focused

Break down complex tasks into smaller, focused, and action-oriented requests. Large, open-ended tasks are more likely to hit iteration limits.

Examples

Issue for generating a merge request

This example shows a well-crafted issue that the Developer Flow can use to generate a merge request.

## Description
The users endpoint currently returns all users at once,
which will cause performance issues as the user base grows.
Implement cursor-based pagination for the `/api/users` endpoint
to handle large datasets efficiently.

## Implementation plan
Add pagination to GET /users API endpoint.
Include pagination metadata in /users API response (per_page, page).
Add query parameters for per page size limit (default 5, max 20).

#### Files to modify
- `src/api/users.py` - Add pagination parameters and logic.
- `src/models/user.py` - Add pagination query method.
- `tests/api/test_users_api.py` - Add pagination tests.

## Acceptance criteria
- Accepts page and per_page query parameters (default: page=5, per_page=10).
- Limits per_page to a maximum of 20 users.
- Maintains existing response format for user objects in data array.

Iterate on merge request review feedback

After reviewing a merge request, you can mention the Developer Flow to address your feedback. For example, in a review comment on a specific line:

@duo-developer-<namespace> move this validation logic into the `BaseService` class
in `app/services/base_service.rb` instead of duplicating it here.

You can also submit a full review and then mention the Developer Flow to address all open threads:

@duo-developer-<namespace> please address the review feedback on this MR.

Split a merge request

If a merge request has grown too large, you can ask the Developer Flow to extract part of it into a separate merge request:

@duo-developer-<namespace> the logging changes in this MR are out of scope.
Split them into a separate MR.

Research an implementation approach

You can ask the Developer Flow to investigate a problem and report back before making any changes:

@duo-developer-<namespace> research whether the `PUT /api/users` endpoint also needs
rate limiting like we added to the `POST /api/users` endpoint.
Post your findings here.

Use images as context

The Developer Flow can read images from your repository or from attachments on issues and merge requests in the same project. Name the image in your prompt.

You can ask the Developer Flow to fix a UI bug shown in a screenshot attached to an issue:

Look at the screenshot attached to issue 1234 and fix the alignment bug it shows.

You can ask the Developer Flow to explain an architecture diagram:

Read docs/architecture.png, explain the data flow, and identify any single points of failure.

You can ask the Developer Flow to turn a whiteboard photo into a design document:

Read whiteboard.jpg and turn it into a design document in docs/design.md.

Use the Developer Flow in Agentic Chat

You can use the Developer Flow in an Agentic Chat conversation to complete different tasks:

  • To accomplish a coding goal, you can enter the following:
    • Use the developer flow to resolve this code review feedback.
    • Use the developer flow to update this dependency.
  • To resolve an issue by opening a merge request, you can enter the following:
    • Resolve this issue.
    • Open a merge request to resolve this issue.