# Custom flows

{{< details >}}

- Tier: [Free](../../../subscriptions/gitlab_credits.md#for-the-free-tier), Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}

{{< collapsible title="Model information" >}}

- LLM: Anthropic [Claude Sonnet 4](https://www.anthropic.com/claude/sonnet)

{{< /collapsible >}}

{{< history >}}

- Introduced as an [experiment](../../../policy/development_stages_support.md) in GitLab 18.4 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_flows`. Disabled by default.
- Changed to [beta](../../../policy/development_stages_support.md) in GitLab 18.7.
- [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/569060) in GitLab 18.7.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/work_items/569060) in GitLab 18.8.
- Feature flag `ai_catalog_flows` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/216969) in GitLab 18.8.
- Pipeline events trigger [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/212797) in GitLab 18.9 as an [experiment](../../../policy/development_stages_support.md) with a [flag](../../../administration/feature_flags/_index.md) named `ai_flow_trigger_pipeline_hooks`. Disabled by default.
- Turning on flows directly in projects as a maintainer [introduced](https://gitlab.com/groups/gitlab-org/-/work_items/20743) in GitLab 18.10 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_project_level_enablement`. Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated by default.
- Available on the Free tier on GitLab.com with GitLab Credits in GitLab 18.10.
- Feature flag `ai_catalog_project_level_enablement` removed in GitLab 18.11.
- **Merge request ready** trigger event type [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/592454) in GitLab 19.0 with a [flag](../../../administration/feature_flags/_index.md) named `merge_request_ready_flow_trigger`. Disabled by default.
- **Merge request code conflict** trigger event type [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/592455) in GitLab 19.1.
- **Merge request** trigger event type with the **Approved** action [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237081) in GitLab 19.1.
- Feature flag `ai_flow_trigger_pipeline_hooks` [removed](https://gitlab.com/gitlab-org/gitlab/-/work_items/587272) in GitLab 19.1.
- **Work item created** trigger event type [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/599985) in GitLab 19.1.
- **Merge request ready** trigger event type [generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/598421) in GitLab 19.1. Feature flag `merge_request_ready_flow_trigger` removed.
- **Work item status changed** trigger event type [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/599983) in GitLab 19.2.
- Feature flag `ai_catalog_flows` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/239459) in GitLab 19.2.
- Changed to [generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/602415) in GitLab 19.2.
- **Merge request** trigger event type with the **Created** action [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242698) in GitLab 19.4.

{{< /history >}}

Custom flows are AI-powered workflows you create and configure to
automate complex, multi-step tasks across your GitLab projects.

## Prerequisites

- Meet the [prerequisites for the GitLab Duo Agent Platform](../_index.md#prerequisites).
- Have [custom flows turned on](#turn-custom-flows-on-or-off).

## Flow visibility

{{< history >}}

- Roles that can view private flows [expanded](https://gitlab.com/gitlab-org/gitlab/-/work_items/582507) in GitLab 18.7.
- Restricted visibility [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/603253) in GitLab 19.3 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_internal_visibility`. Enabled by default.
- Generally available in GitLab 19.4. Feature flag `ai_catalog_internal_visibility` removed.

{{< /history >}}

When you create a custom flow, you select a project to manage it and choose whether the flow is public, private, or restricted.

Public flows:

- Can be viewed by anyone on the instance and can be turned on in any project that meets the prerequisites.

Restricted flows:

- Can be viewed and used by members of any project in the top-level group of the managing project.
- Can be turned on in other projects in the same top-level group.
- Cannot be viewed or turned on outside that top-level group.
- Cannot be viewed in the AI Catalog in Explore.
- Can be created only from a project, not from the AI Catalog in Explore.

You cannot make a public flow restricted if the flow has been turned on by a project outside of that top-level group.

Private flows:

- Can be viewed only by:
  - Members of the managing project who have the Guest, Planner, Reporter, Developer,
    Maintainer, or Owner role.
  - Users with the Owner role for the top-level group.
- Cannot be turned on in projects other than the managing project, or in groups
  other than the top-level group.

You cannot make a public or restricted flow private if the flow has been turned on by a project other than the managing project.

## View the flows for your project

Prerequisites:

- You must have the Developer, Maintainer, or Owner role for the project.

To view a list of flows associated with your project:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
   - To view flows turned on in the project, select the **Enabled** tab.
   - To view flows managed by the project, select the **Managed** tab.

Select a flow to view its details.

## Create a flow

{{< history >}}

- Restricted visibility [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/603253) in GitLab 19.3 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_internal_visibility`. Enabled by default.
- GitLab flow builder [introduced](https://gitlab.com/groups/gitlab-org/editor-extensions/-/work_items/236) in GitLab for VS Code 6.87.0 during the GitLab 19.3 release, with a VS Code extension setting named `gitlab.featureFlags.flowBuilder`. Disabled by default. This is a [beta](../../../policy/development_stages_support.md) feature.
- Generally available in GitLab 19.4. Feature flag `ai_catalog_internal_visibility` removed.

{{< /history >}}

The GitLab flow builder in VS Code is controlled by the VS Code extension setting `gitlab.featureFlags.flowBuilder`.
For more information, see the history.

You can create a flow from a project, with the AI Catalog, or with the GitLab flow builder in VS Code.

A custom flow can use AI Catalog agents as subagents.
This feature is in [beta](../../../policy/development_stages_support.md#beta).
For the YAML, the rules, and the flag, see [`include`](custom_flows_schema.md#include).

Prerequisites:

- You must have the Maintainer or Owner role for the project.

{{< tabs >}}

{{< tab title="From a project" >}}

To create a flow:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
1. Select **New flow**.
1. Under **Basic information**:
   1. In **Display name**, enter a name.
   1. In **Description**, enter a description.
1. Under **Visibility & access**, for **Visibility**, select **Private**, **Restricted**, or **Public**.
1. Under **Configuration**:
   1. Select **Flow**.
   1. In the editor, enter your flow configuration:

      - For more information on the YAML syntax and schema, see [custom flow YAML schema](custom_flows_schema.md).
1. Select **Create flow**.

{{< /tab >}}

{{< tab title="AI Catalog" >}}

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Flows** tab.
1. Select **New flow**.
1. Under **Basic information**:
   1. In **Display name**, enter a name.
   1. In **Description**, enter a description.
1. Under **Visibility & access**, for **Visibility**, select **Private** or **Public**.
1. Under **Configuration**:
   1. Select **Flow**.
   1. In the editor, enter your flow configuration:

      - For more information on the YAML syntax and schema, see [custom flow YAML schema](custom_flows_schema.md).
1. Select **Create flow**.

{{< /tab >}}

{{< tab title="VS Code" >}}

Prerequisites:

- [Install and configure the GitLab for VS Code extension](../../../editor_extensions/visual_studio_code/setup.md).
- Turn on the `gitlab.featureFlags.flowBuilder` VS Code extension setting.
- To run a flow: GitLab Duo Agent Platform must be turned on for the project, and you must have at least the Developer role.
- To publish a flow to the AI Catalog: Have the Maintainer or Owner role for the managing project.

> [!note]
> When you publish a flow from the GitLab flow builder, only **Private** and **Public** visibility options are available.
> The **Restricted** visibility option is available only when you create a flow from the GitLab UI.

In VS Code, you can use the GitLab flow builder to create a custom flow.

1. In your project, in VS Code, open a new YAML file.
1. Whilst in the YAML file, select **Open GitLab Flow Builder**.
1. Select the following components to build the flow. Complete the fields:
   - **Agent**: runs multi-step reasoning with tool use and iterates until its goal is complete.
   - **Tool**: runs a single specific tool with fixed inputs; deterministic, no LLM involved.
   - **AI Task**: makes a single LLM call that produces one result (for example, summarize, classify, or draft).
     Use **AI Task** instead of **Agent** when you need a single model response rather than multi-step work.
     An Agent runs in a loop and can use tools; an AI Task makes one model call and returns one result.
   - **Human Input**: pauses the flow and waits for user input or approval before continuing.
1. Optional. Edit the YAML file to update the flow, and check the flow in the
   GitLab flow builder.

   > [!note]
   > The flow YAML must comply with the [flow registry v1 specification](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/docs/flow_registry/v1.md) syntax.
1. To test your flow, select **Run**. In the **Execution Console**, select **Execute**.
   Check the flow output, and update the flow as needed.
1. Select **Save** or **Save as** to save the flow.
1. To publish the flow to the AI Catalog, select **Publish** and complete the
   fields.

> [!note]
> The GitLab flow builder can publish a flow to the AI Catalog, but turning on a flow in a project
> and attaching automations is done in the GitLab UI only.

{{< /tab >}}

{{< /tabs >}}

The flow appears in the AI Catalog.

## Turn on a flow

{{< history >}}

- Turning on a public flow for multiple projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/600526) in GitLab 19.2 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_bulk_item_consumer_create`. Enabled by default.
- Feature flag `ai_catalog_bulk_item_consumer_create` removed in GitLab 19.4.
- Turning on a flow for all projects in a top-level group [introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/627512) in GitLab 19.5 [with a feature flag](../../../administration/feature_flags/_index.md) named `ai_catalog_group_inherited_consumers`. Disabled by default.

{{< /history >}}

Turn on a flow to trigger it from an issue, merge request, or discussion.

When you turn on a flow in a project:

- The flow is turned on in the top-level group for that project at the same time.
- You add an [automation](../automations/_index.md) to specify which events trigger the
  flow. Some of the events involve the service account user. For more
  information, see [composite identity](../composite_identity.md).

You can turn on a flow or agent up to 30 times per minute.

{{< tabs >}}

{{< tab title="From the managing project" >}}

Prerequisites:

- Have the Maintainer or Owner role for the project.

To turn on a flow:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
1. Select the **Managed** tab, then select the flow you want to turn on.
1. In the upper-right corner, select **Enable**.
1. Optional. In the **Instructions** field, enter what the flow should do each time it runs.
   For more information, see [Add instructions](../automations/_index.md#add-instructions).
1. Under **Runs when**, review the [events](../automations/_index.md#event-types) that trigger the flow.
   By default, the flow runs on **Mention**, **Assign**, and **Assign reviewer**.
   - To add an event, select **Add trigger** > **On an event**.
   - To change or remove an event, select the edit or delete icon next to it.
1. Select **Enable**.

{{< /tab >}}

{{< tab title="From the top-level group" >}}

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

When you turn on a flow in a top-level group, the flow is turned on for all projects in the group.
Projects that you create in or transfer to the group later also get the flow.
You do not have to turn on the flow in each project.

Prerequisites:

- Have the Maintainer or Owner role for the top-level group.
- The flow is public, or restricted to the same top-level group.

To turn on a flow for all projects in a top-level group:

1. In the top bar, select **Search or go to** and find your top-level group.
1. In the left sidebar, select **AI** > **Flows**.
1. Select the flow you want to turn on.
1. In the upper-right corner, select **Enable for all projects**.
1. Under **Conditions**, review the [events](../automations/_index.md#event-types) that trigger the flow.
   By default, the flow runs on **Mention**, **Assign**, and **Assign reviewer**.
   - To add an event, select **Add condition** > **On an event**.
   - To change or remove an event, select the edit or delete icon next to it.
1. Optional. To tell the flow what to do for an event, edit the event, then enter text in the **Instructions** field.
   For more information, see [Add instructions](../automations/_index.md#add-instructions).
1. Select **Enable for all projects**.

   If the flow is already turned on in one or more projects in the group,
   select **Replace and enable for all projects**.
   The project configurations are deleted and the group configuration is used instead.

In the group, the flow is labeled **Enabled for all projects**.
In each project, the flow is labeled **Enabled by** followed by the group name.

The service account for the flow is added to each project in the group with the Developer role.

To turn off the flow for all projects, on the flow's page, select **Disable for all projects**, then select **Disable**.

{{< /tab >}}

{{< tab title="From the AI Catalog" >}}

Prerequisites:

- You must have the Maintainer or Owner role for the project.

To turn on a flow:

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Flows** tab.
1. Select the flow you want to turn on.
1. In the upper-right corner, select **Enable**.
1. Under **Select projects**, select the project you want to turn on the flow in.

   To turn on a public or restricted flow for multiple projects, select the relevant projects.
   You can select up to 100 projects.
   You can turn on a flow for multiple projects up to 10 times per minute.

1. Under **Conditions**, review the [events](../automations/_index.md#event-types) that trigger the flow.
   By default, the flow runs on **Mention**, **Assign**, and **Assign reviewer**.
   - To add an event, select **Add condition** > **On an event**.
   - To change or remove an event, select the edit or delete icon next to it.
1. Optional. For an event, in the **Instructions** field, enter text that tells the flow what to do.
   For more information, see [Add instructions](../automations/_index.md#add-instructions).
1. Select **Enable**.

{{< /tab >}}

{{< /tabs >}}

The flow appears in the group and project **AI** > **Flows** pages.
If you turned on the flow in a project, maintainers of other projects in the top-level group
can also turn on the flow in their projects by using the **From the AI Catalog** tab.

A service account is created in the group. The name of the account
follows this naming convention: `ai-<flow>-<group>`.

## Manage automation conditions

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255119) in GitLab 19.5.

{{< /history >}}

You can manage a flow's automations from its configuration page.

For more information about automations, including how to create one, see [automations](../automations/_index.md).

Prerequisites:

- The Maintainer or Owner role for the project.

### Turn an automation on or off

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
1. Select the flow you want to manage.
1. In the **Trigger conditions** section, for the automation you want to turn on or off,
   select the toggle.

### Edit an automation

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
1. Select the flow you want to manage.
1. In the **Trigger conditions** section, for the automation you want to change,
   select **Trigger actions** ({{< icon name="ellipsis_v" >}}) > **Edit**.
1. Make the changes and select **Save changes**.

### Delete an automation

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **AI** > **Flows**.
1. Select the flow you want to manage.
1. In the **Trigger conditions** section, for the automation you want to delete,
   select **Trigger actions** ({{< icon name="ellipsis_v" >}}) > **Delete**.
1. On the confirmation dialog, select **Delete**.

## Turn off a flow

Prerequisites:

- For groups, you must have the Maintainer or Owner role.
- For projects, you must have the Maintainer or Owner role.

To turn off a flow:

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Flows**.
1. Find the flow you want to remove and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Disable**.
1. On the confirmation dialog, select **Disable**.

The flow no longer appears in the project or group, and can't be run. Any service accounts or automations associated with the flow are also removed.
You can turn off a flow or agent up to 30 times per minute.

## Use a flow

Prerequisites:

- You must have the Developer, Maintainer, or Owner role for the project.
- The flow must be turned on in the project.

To use a flow:

1. In your project, open an issue, merge request, or epic.
1. To trigger the flow, mention, assign, or request a review from the flow service account user. By default, the user has the name `ai-<flow>-<group>`.

   For example, if you turn on a flow called `Security scanner` in the `GitLab Duo` group, the service account user is `ai-security-scanner-gitlab-duo`.
1. After the flow has completed the task, you see a confirmation, and either a ready-to-merge change or an inline comment.

You can also start a flow from a [GitLab Duo Agentic Chat slash command](../../gitlab_duo_chat/agentic_chat.md#trigger-a-flow-with-a-slash-command) if the flow has been turned on for the project.

> [!warning]
> The service account can access all projects that both:
>
> - You have access to.
> - The flow has been added to.

## Duplicate a flow

To make changes to a flow without overwriting the original, create a copy of an existing flow.

Prerequisites:

- You must have the Maintainer or Owner role for the project.

{{< tabs >}}

{{< tab title="GitLab UI" >}}

To duplicate a flow:

1. In the top bar, select **Search or go to** > **Explore**.
1. Select **AI Catalog**, then select the **Flows** tab.
1. Select the flow you want to duplicate.
1. In the upper-right corner, select **Actions** ({{< icon name="ellipsis_v" >}}) > **Duplicate**.
1. Select the project where you want to duplicate the flow.
1. Optional. Edit any fields you want to change.
1. Select **Create flow**.

{{< /tab >}}

{{< tab title="VS Code" >}}

There is no dedicated duplicate action in the GitLab flow builder.
To create a copy of a flow, use **Save As**, which saves the open flow as a new file.
You can also open a copied YAML file directly in the flow builder.

> [!note]
> Publishing a copy creates a new catalog item that is not linked to the original.

{{< /tab >}}

{{< /tabs >}}

## Edit a flow

Edit a flow to change its configuration.

Prerequisites:

- You must be a member of the managing project and have the Maintainer or Owner role.

{{< tabs >}}

{{< tab title="GitLab UI" >}}

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Flows**.
1. Select the flow you want to edit.
1. In the upper-right corner, select **Edit**.
1. Edit any fields you want to change, then select **Save changes**.

{{< /tab >}}

{{< tab title="VS Code" >}}

1. In your project, in VS Code, open the flow's YAML file.
1. Whilst in the YAML file, select **Open GitLab Flow Builder**.
1. Edit the flow in the GitLab flow builder.
1. To test your flow, select **Run**. In the **Execution console**, select **Execute**.
   Check the flow output, and update the flow as needed.
1. Select **Save** or **Save as** to save the flow.

{{< /tab >}}

{{< /tabs >}}

## Hide a flow

Hide a flow to remove it from the AI Catalog.

After you hide a flow, users can't turn it on. However, they can still trigger it in the groups and projects it is already turned on in.

Prerequisites:

- You must be a member of the managing project and have the Maintainer or Owner role.

To hide a flow:

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Flows**.
1. Find the flow you want to hide and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Hide**.
1. In the confirmation dialog, select **Confirm**.

## Delete a flow

Delete a flow to remove it from the instance. If a project other than the managing project has turned off the
flow, the flow is hidden instead of removed.

Prerequisites:

- You must be an administrator.

1. In the top bar, select **Search or go to** and find your group or project.
1. Select **AI** > **Flows**.
1. Find the flow you want to delete and select **Actions** ({{< icon name="ellipsis_v" >}}) > **Delete**.
1. In the confirmation dialog, select **Delete**.

## Authenticate to the GitLab API

Custom flows have a GitLab OAuth token available as `GITLAB_TOKEN` (also exposed as `GITLAB_OAUTH_TOKEN`).
These tokens are limited to the scope granted to them. They can only access
[GitLab API endpoints with the `ai_workflows` scope](../../../editor_extensions/software_development.md#apis-that-the-flow-has-access-to).
Endpoints outside that scope are refused even when the token is sent correctly.

If you write scripts that call the GitLab API directly, send the token as an `Authorization: Bearer` token.
If you use the `PRIVATE-TOKEN` header to send the token, the API returns `401 Unauthorized`.

```shell
curl --header "Authorization: Bearer $GITLAB_TOKEN" \
  "$GITLAB_BASE_URL/api/v4/user"
```

The flow's built-in tools and the `glab` CLI call the API correctly.

## Group sharing and flows

When you turn on a flow in a group, a related service account is automatically created. The service account:

- Uses [composite identity authentication](../composite_identity.md) to ensure that the flow can never access more than the user who runs the flow.
- Is added as a member to any project under the top-level group that turns on the flow, so the flow can't access resources outside that group.
- Is granted access to any additional groups that are shared with the top-level group. The service account is treated like any other group member for group sharing.

> [!note]
> Sharing flow service accounts across multiple top-level groups can create unintended access
> permissions and security risks.

## Turn custom flows on or off

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/594615) in GitLab 19.0.

{{< /history >}}

By default, custom flows are turned on.
You can turn them on or off for a top-level group or for an instance.

When custom flows are turned off:

- Users cannot create, turn on, turn off, or execute custom flows.
- Existing custom flows are no longer visible
  in the project under **AI** > **Flows** > **Enabled**.
- Custom flows created in the project appear
  under **AI** > **Flows** > **Managed**, but cannot be executed.
- [Foundational flows](foundational_flows/_index.md) remain available.

{{< tabs >}}

{{< tab title="GitLab.com" >}}

Prerequisites:

- You must have the Owner role for the group.

1. In the top bar, select **Search or go to** and find your group.
1. In the left sidebar, select **Settings** > **GitLab Duo**.
1. Select **Change configuration**.
1. Under **Custom and external agents and flows**, select or clear the
   **Allow custom flows** checkbox.
1. Select **Save changes**.

This setting cascades to all subgroups in the group.

{{< /tab >}}

{{< tab title="GitLab Self-Managed" >}}

Prerequisites:

- You must be an administrator.

1. In the upper-right corner, select **Admin**.
1. In the left sidebar, select **GitLab Duo**.
1. Select **Change configuration**.
1. Under **Custom and external agents and flows**, select or clear the
   **Allow custom flows** checkbox.
1. Select **Save changes**.

When the instance-level setting is turned off,
group-level settings cannot override it.

{{< /tab >}}

{{< /tabs >}}

