Custom flows | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions GitLab Duo Agent Platform Getting started Tutorials Availability Agentic Chat AI Catalog Agents Flows Foundational flows Custom flows YAML schema Configure flow execution Triggers Sessions Customization Code Suggestions Models Contextual awareness Composite identity Authentication Security threats Model Context Protocol Semantic code search Troubleshooting GitLab Duo Non-Agentic Data usage * GitLab Docs / * GitLab Duo / * GitLab Duo Agent Platfor… / * Flows / * Custom flows Help us learn about your current experience with the documentation. Take the survey . Custom flows * Tier : Free , Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Model information * LLM: Anthropic Claude Sonnet 4 History * Introduced as an experiment in GitLab 18.4 with a feature flag named ai_catalog_flows . Disabled by default. * Changed to beta in GitLab 18.7. * Enabled on GitLab.com in GitLab 18.7. * Enabled on GitLab Self-Managed and GitLab Dedicated in GitLab 18.8. * Feature flag ai_catalog_flows enabled by default in GitLab 18.8. * Pipeline events trigger introduced in GitLab 18.9 as an experiment with a flag named ai_flow_trigger_pipeline_hooks . Disabled by default. * Enabling directly in projects as a maintainer introduced in GitLab 18.10 with a feature flag 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 in GitLab 19.0 with a flag named merge_request_ready_flow_trigger . Disabled by default. * Merge request code conflict trigger event type introduced in GitLab 19.1. * Merge request trigger event type with the Approved action introduced in GitLab 19.1. * Feature flag ai_flow_trigger_pipeline_hooks removed in GitLab 19.1. * Work item created trigger event type introduced in GitLab 19.1. * Merge request ready trigger event type generally available in GitLab 19.1. Feature flag merge_request_ready_flow_trigger removed. * Work item status changed trigger event type introduced in GitLab 19.2. * Feature flag ai_catalog_flows removed in GitLab 19.2. * Changed to generally available in GitLab 19.2. * Merge request trigger event type with the Created action introduced in GitLab 19.4. 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 . * Have custom flows turned on . Flow visibility History * Roles that can view private flows expanded in GitLab 18.7. * Restricted visibility introduced in GitLab 19.3 with a feature flag named ai_catalog_internal_visibility . Enabled by default. * Generally available in GitLab 19.4. Feature flag ai_catalog_internal_visibility removed. 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 enabled 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 enabled 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: * In the top bar, select Search or go to and find your project. * In the left sidebar, select AI > 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 History * Restricted visibility introduced in GitLab 19.3 with a feature flag named ai_catalog_internal_visibility . Enabled by default. * GitLab flow builder introduced 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 feature. * Generally available in GitLab 19.4. Feature flag ai_catalog_internal_visibility removed. 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. You cannot define a custom flow to call a specific custom agent from a project or the AI Catalog. Custom flows create and use their own agents based on their YAML configuration. Prerequisites: * You must have the Maintainer or Owner role for the project. From a project To create a flow: * In the top bar, select Search or go to and find your project. * In the left sidebar, select AI > Flows . * Select New flow . * Under Basic information : * In Display name , enter a name. * In Description , enter a description. * Under Visibility & access , for Visibility , select Private , Restricted , or Public . * Under Configuration : * Select Flow . * In the editor, enter your flow configuration: * For more information on the YAML syntax and schema, see custom flow YAML schema . * Select Create flow . AI Catalog * In the top bar, select Search or go to > Explore . * Select AI Catalog , then select the Flows tab. * Select New flow . * Under Basic information : * In Display name , enter a name. * In Description , enter a description. * Under Visibility & access , for Visibility , select Private or Public . * Under Configuration : * Select Flow . * In the editor, enter your flow configuration: * For more information on the YAML syntax and schema, see custom flow YAML schema . * Select Create flow . VS Code Prerequisites: * Install and configure the GitLab for VS Code extension . * Enable 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. 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. * In your project, in VS Code, open a new YAML file. * Whilst in the YAML file, select Open GitLab Flow Builder . * 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. * Optional. Edit the YAML file to update the flow, and check the flow in the GitLab flow builder. The flow YAML must comply with the flow registry v1 specification syntax. * To test your flow, select Run . In the Execution Console , select Execute . Check the flow output, and update the flow as needed. * Select Save or Save as to save the flow. * To publish the flow to the AI Catalog, select Publish and complete the fields. The GitLab flow builder can publish a flow to the AI Catalog, but enabling a flow in a project and attaching triggers is done in the GitLab UI only. The flow appears in the AI Catalog. Enable a flow History * Enabling a public flow for multiple projects introduced in GitLab 19.2 with a feature flag named ai_catalog_bulk_item_consumer_create . Enabled by default. * Feature flag ai_catalog_bulk_item_consumer_create removed in GitLab 19.4. Enable a flow to trigger it from an issue, merge request, or discussion. When you enable a flow in a project: * The flow is enabled in the top-level group for that project at the same time. * You add a trigger to specify which events trigger the flow. Some of the trigger events involve the service account user. For more information, see composite identity . Prerequisites: * You must have the Maintainer or Owner role for the project. From the managing project To enable a flow: * In the top bar, select Search or go to and find your project. * In the left sidebar, select AI > Flows . * Select the Managed tab, then select the flow you want to enable. * In the upper-right corner, select Enable . * Under Project , select the project you want to enable the flow in. * For Add triggers , select: * The event types that trigger the flow . * If needed for the trigger event type, a trigger event action. * Select Enable . From the AI Catalog To enable a flow: * In the top bar, select Search or go to > Explore . * Select AI Catalog , then select the Flows tab. * Select the flow you want to enable. * In the upper-right corner, select Enable . * Under Project , select the project you want to enable the flow in. To enable a public or restricted flow for multiple projects, from the Project dropdown list, select the relevant projects. You can select up to 100 projects. * For Add triggers , select: * The event types that trigger the flow . * If needed for the trigger event type, a trigger event action. * Select Enable . The flow appears in the group and project AI > Flows pages. Members of any project in the top-level group can now enable the flow in their project. A service account is created in the group. The name of the account follows this naming convention: ai-<flow>-<group> . Enable in a project If a flow is already enabled in a top-level group, you can enable it in the group s projects. Prerequisites: * You must have the Maintainer or Owner role for the project. * The flow must be enabled in the project s top-level group. To enable a flow in a project: * In the top bar, select Search or go to and find your project. * In the left sidebar, select AI > Flows . * In the upper-right corner, select Enable flow from group . * From the dropdown list, select the flow you want to enable. * For Add triggers , select: * The event types that trigger the flow . * If needed for the trigger event type, a trigger event action. * Select Enable . The flow appears in the project s AI > 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 Maintainer or Owner role. * For projects, you must have the Maintainer or Owner role. To disable a flow: * In the top bar, select Search or go to and find your group or project. * Select AI > Flows . * Find the flow you want to remove and select Actions ( ) > Disable . * 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. Use a flow Prerequisites: * You must have the Developer, Maintainer, or Owner role for the project. * The flow must be enabled in the project. To use a flow: * In your project, open an issue, merge request, or epic. * 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 Security scanner in the GitLab Duo group, the service account user is ai-security-scanner-gitlab-duo . * After the flow has completed the task, you see a confirmation, and either a ready-to-merge change or an inline comment. 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. GitLab UI To duplicate a flow: * In the top bar, select Search or go to > Explore . * Select AI Catalog , then select the Flows tab. * Select the flow you want to duplicate. * In the upper-right corner, select Actions ( ) > Duplicate . * Optional. Edit any fields you want to change. * Select Create flow . 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. Publishing a copy creates a new catalog item that is not linked to the original. 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. GitLab UI * In the top bar, select Search or go to and find your group or project. * Select AI > Flows . * Select the flow you want to edit. * In the upper-right corner, select Edit . * Edit any fields you want to change, then select Save changes . VS Code * In your project, in VS Code, open the flow s YAML file. * Whilst in the YAML file, select Open GitLab Flow Builder . * Edit the flow in the GitLab flow builder. * To test your flow, select Run . In the Execution console , select Execute . Check the flow output, and update the flow as needed. * Select Save or Save as to save the flow. Hide a flow Hide a flow to remove it from the AI Catalog. After you hide a flow, users can t enable it. However, they can still trigger it in the groups and projects it is already enabled in. Prerequisites: * You must be a member of the managing project and have the Maintainer or Owner role. To hide a flow: * In the top bar, select Search or go to and find your group or project. * Select AI > Flows . * Find the flow you want to hide and select Actions ( ) > Hide . * In the confirmation dialog, select Confirm . Delete a flow Delete a flow to permanently remove it from the instance. Prerequisites: * You must be an administrator. * In the top bar, select Search or go to and find your group or project. * Select AI > Flows . * Find the flow you want to delete and select Actions ( ) > Delete . * 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 . 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 . 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 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. 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 in GitLab 19.0. 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, enable, disable, 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 remain available. GitLab.com Prerequisites: * You must have the Owner role for the group. * In the top bar, select Search or go to and find your group. * In the left sidebar, select Settings > GitLab Duo . * Select Change configuration . * Under Custom and external agents and flows , select or clear the Allow custom flows checkbox. * Select Save changes . This setting cascades to all subgroups in the group. GitLab Self-Managed Prerequisites: * You must be an administrator. * In the upper-right corner, select Admin . *