Custom flows

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

Flow visibility

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

Public flows:

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

Private flows:

• Can be viewed only by members of the managing project who have at least the Developer role, and by users with the Owner role for the top-level group.
• Cannot be enabled in projects other than the managing project, or in groups other than the top-level group.

You cannot change a private flow to public if the flow is currently enabled.

View the flows for your project

Prerequisites:

• You must have at least the Developer role for the project.

To view a list of flows associated with your project:

1. On the top bar, select Search or go to and find your project.
2. Select Automate > Flows.
   • To view flows enabled 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

Prerequisites:

• You must have at least the Maintainer role for the project.

To create a flow:

1. On the top bar, select Search or go to and find your project.
2. Select Automate > Flows.
3. Select New flow.
4. Under Basic information:
   1. In Display name, enter a name.
   2. In Description, enter a description.
5. Under Visibility & access, for Visibility, select Private or Public.
6. Under Configuration:
   1. Select Flow.
   2. In the editor, enter your flow configuration. To learn how to write custom flow YAML, see the flow registry framework documentation.
7. Select Create flow.

The flow appears in the AI Catalog.

Enable a flow

Enable a flow to trigger it from an issue, merge request, or discussion. To enable a flow, you must:

1. Enable it in a top-level group.
2. Enable it in the project you want to use it in.

Enable in a top-level group

Prerequisites:

• You must have the Owner role for the group.

To enable a flow in a top-level group:

1. On the top bar, select Search or go to > Explore.
2. Select AI Catalog, then select the Flows tab.
3. Select the flow you want to enable.
4. In the upper-right corner, select Enable in group.
5. From the dropdown list, select the group you want to enable the flow in.
6. Select Enable.

The flow appears in the group’s Automate > Flows page.

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

Enable in a project

Prerequisites:

• You must have at least the Maintainer role for the project.
• The flow must be enabled in the project’s top-level group.

To enable a flow in a project:

1. On the top bar, select Search or go to and find your project.
2. Select Automate > Flows.
3. In the upper-right corner, select Enable flow from group.
4. From the dropdown list, select the flow you want to enable.
5. For Add triggers, select which events trigger the flow:
   • Mention: When the service account user is mentioned in a comment on an issue or merge request.
   • Assign: When the service account user is assigned to an issue or merge request.
   • Assign reviewer: When the service account user is assigned as a reviewer to a merge request.
6. Select Enable.

The flow appears in the project’s Automate > Flows list.

The top-level group’s service account is added to the project. This account is assigned the Developer role.

Disable a flow

Prerequisites:

• For groups, you must have the Owner role.
• For projects, you must have at least the Maintainer role.

To disable a flow:

1. On the top bar, select Search or go to and find your group or project.
2. Select Automate > Flows.
3. Find the flow you want to remove and select Actions ( ) > Disable.
4. 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 triggers associated with the flow are also removed.

Create a trigger

You must now create a trigger, which determines when the flow runs.

For example, you can specify the flow to be triggered when you mention the flow service account user in a discussion, or when you assign the service account as a reviewer.

When you enable a flow in a project, you also create triggers.

Use a flow

Prerequisites:

• You must have at least the Developer role for the project.
• The flow must be enabled in the project.

To use a flow:

1. In your project, open an issue, merge request, or epic.

2. 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 enable a flow called Code review flow in the GitLab Duo group, the service account user is ai-code-review-flow-gitlab-duo.

3. After the flow has completed the task, you see a confirmation, and either a ready-to-merge change or an inline comment.

Duplicate a flow

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

Prerequisites:

• You must have at least the Maintainer role for the project.

To duplicate a flow:

1. On the top bar, select Search or go to > Explore.
2. Select AI Catalog, then select the Flows tab.
3. Select the flow you want to duplicate.
4. In the upper-right corner, select Actions ( ) > Duplicate.
5. Optional. Edit any fields you want to change.
6. Select Create flow.

Manage flows

Edit a flow to change its configuration, or delete it to remove it from the AI Catalog.

Prerequisites:

• You must be a member of the managing project and have at least the Maintainer role.

1. On the top bar, select Search or go to > Explore.
2. Select AI Catalog, then select the Flows tab.
3. Select the flow you want to manage.
   • To edit a flow:
     1. In the upper-right corner, select Edit.
     2. Edit any fields you want to change, then select Save changes.
   • To delete a flow:
     1. In the upper-right corner, select Actions ( ) > Delete.
     2. On the confirmation dialog, select Delete.

Group sharing and flows

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

• Uses composite identity authentication 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 enables 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.