Triggers

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

Version history

Introduced in GitLab 18.3 with a feature flag named ai_flow_triggers. Enabled by default.
Changed in GitLab 18.8 to require an additional flag named ai_catalog_create_third_party_flows. Disabled by default.
Generally available in GitLab 18.8.

[!flag] To change the location of your flow configuration file, you must enable a feature flag. For more information, see the history.

A trigger determines when a flow or external agent runs. A trigger cannot be created for a custom agent or foundational agent.

For example, you can specify flows to be triggered when you mention them in a discussion, or when you assign them as a reviewer.

Create a trigger

Version history

Assign and Assign reviewer event types introduced in GitLab 18.5.
Pipeline events trigger event type introduced in GitLab 18.9 as an experiment with a flag named ai_flow_trigger_pipeline_hooks. Disabled by default.
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.
Merge request ready and Merge request code conflict event types consolidated into the Merge request event type as the Marked ready and Merge conflict actions in GitLab 19.2.
Trigger creation form changed to add conditions one at a time in GitLab 19.3.
Merge request trigger event type with the Created action introduced in GitLab 19.4.
Status filter for the Work item trigger event type with the Status changed action introduced in GitLab 19.4.

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

Prerequisites:

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

To create a trigger:

In the top bar, select Search or go to and find your project.
In the left sidebar, select AI > Triggers.
Select New flow trigger.
In Description, enter a description for the trigger.
In the Conditions section, for each condition that should start the trigger:
1. Select Add condition, then select On an event.
2. From the Event dropdown list, select a trigger event type.
3. If the event type needs configuration, from the Run when dropdown list select one or more trigger event actions.
4. Select Add event.
From the Service account dropdown list, select a user to be the composite identity.
For Configuration source, select one of the following:
- AI Catalog: From the flows configured for this project, select a flow for the trigger to execute.
- Configuration path: Enter the path to the flow configuration file (for example, .gitlab/duo/flows/claude.yaml). To view this option, the ai_catalog_create_third_party_flows flag must be enabled.
Optional. To give an event its own instructions, in the Conditions section, for that event select Edit event ({pencil}). Enter the text in the Goal field, then select Save. For more information, see Add a goal.
Select Create flow trigger.

The trigger now appears in AI > Triggers.

Trigger event types

Name	Description	Configuration
Mention	When the service account user is mentioned in a comment on an issue or merge request.	None
Assign	When the service account user is assigned to an issue or merge request.	None
Assign reviewer	When the service account user is assigned as a reviewer to a merge request.	None
Pipeline events	When a pipeline changes state.	From the Run when dropdown list, select one or more of the following: - Running - Passed - Failed - Canceled
Merge request	When a selected merge request action occurs.	From the Run when dropdown list, select one of the following: - Approved: When a merge request has all required approvals. - Created: When someone creates a merge request, draft or ready, and GitLab generates its diff. GitLab syncs code owner approval rules against that diff before the flow runs, unless the merge request joins a merge train or GitLab cannot reload the diff. - Marked ready: When a draft merge request is marked as ready for review. - Merge conflict: When a merge request can no longer be merged due to a code conflict.
Work item	When a selected work item action occurs.	From the Run when dropdown list, select one of the following: - Created: When a work item is created - Status changed: When a work item's status changes. When Status changed is the only selected action, you can select one or more statuses to run the flow only when the work item changes to one of them.

Add a goal

Version history

Goal for each condition introduced in GitLab 19.5 with a flag named ai_flow_trigger_goals. Disabled by default.

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

A goal is text that tells the flow what to do. Add a goal to a condition when you want the flow to do a specific task for that event. Two trigger events can run the same flow with different goals.

Prerequisites:

You must have the Maintainer or Owner role for the project.
The trigger must use a flow that accepts a goal. Custom flows and external agents accept a goal, and so does a trigger that uses a configuration path. Foundational flows, such as Code Review, do not accept a goal.

To add a goal to a condition in an existing trigger:

In the top bar, select Search or go to and find your project.
In the left sidebar, select AI > Triggers.
For the trigger you want to change, select More actions ({ellipsis_v}) > Edit trigger.
In the Conditions section, for the condition you want to change, select Edit event ({pencil}).
In the Goal field, enter the goal. Use 4096 characters or fewer.
Select Save.
Select Save changes.

The goal appears under the condition in the Conditions section.

A goal belongs to one condition, not to the whole trigger. For a Merge request event, one goal applies to every action that you select in Run when.

You can also add a goal when you create a trigger or when you enable a flow. In the trigger form, the Goal field stays hidden until you set Configuration source. If you select AI Catalog, you must also select a flow that accepts a goal.

Write a goal

The goal goes in front of the information that the event supplies. The goal never replaces that information. Do not repeat that information in the goal.

The flow also receives:

For a mention event, the comment that the person wrote.
For every other event, a short context block. The block gives the web address of the merge request, work item, or project. The block also gives the action that occurred.

Warning

The flow runs with the permissions of the service account. No person is present to answer questions from the flow. Write the goal so that the flow can complete it alone.

To write a goal that gets the result you want:

Give the flow one clear task.
Do not name the resource. The context block already names it.
Give all the details that the flow needs. The flow cannot ask you for more.
Say what the output must look like. For example, give the format or the maximum length.
Ask only for work that the service account has permission to do.

The following table shows example goals.

Event	Goal
Mention	`Answer the question in a comment. Keep the reply under 200 words.`
Merge request, Created action	`Review the code changes and list any missing tests in a comment.`
Work item, Created action	`Add a severity label and a test plan.`

Edit a trigger

In the top bar, select Search or go to and find your project.
In the left sidebar, select AI > Triggers.
For the trigger you want to change, select More actions ({ellipsis_v}) > Edit trigger.
Make the changes and select Save changes.

You can also edit a custom flow's trigger on its configuration page, under Trigger conditions.

Turn a trigger on or off

Version history

Introduced in GitLab 19.4.

Turn off a trigger to disable it and retain its configuration. After you turn a trigger off, it stops running automatically after its configured actions, and remains in the list of triggers.

In the top bar, select Search or go to and find your project.
In the left sidebar, select AI > Triggers.
For the trigger you want to turn on or off, on the right side, select the toggle.

You can also turn a custom flow's trigger on or off on its configuration page, under Trigger conditions.

Delete a trigger

In the top bar, select Search or go to and find your project.
In the left sidebar, select AI > Triggers.
For the trigger you want to delete, select More actions ({ellipsis_v}) > Delete trigger.
On the confirmation dialog, select OK.

You can also delete a custom flow's trigger on its configuration page, under Trigger conditions.

Actions that don't initiate a trigger

All trigger event types require a human user to perform the triggering action. A non-human user such as a bot user, service account user, or another flow, cannot activate a trigger.

This restriction applies to all trigger event types. For example, a flow cannot trigger another flow by mentioning the service account in a comment.

GitLab Credits consumption for triggered flows

A flow started by a trigger runs as the trigger's service account, which makes the service account the billing subject for the flow's GitLab Credits consumption. The human user who performed the triggering action provides the delegated authorization context for the flow to run, but is not the billing subject.

Service accounts are non-human subjects and they do not receive included credits. Their consumption is billed at the namespace from the Monthly Commitment Pool and On-Demand credits. For more information about these types of credits, see GitLab Credits.

For example, a trigger runs a flow when a merge request receives all required approvals, and the merge request requires three approvals. When the third approver approves the merge request, the trigger runs the flow as the configured service account, and the credit consumption is attributed to the service account rather than to the third approver.

This attribution applies to every trigger event type. For example, it also applies to flows triggered by a pipeline state change, a work item status change, or a mention.

In the GitLab Credits dashboard, this credit consumption displays in the Usage by user tab as a row for the service account with an Automated flow badge. It does not display under the human user who triggered the flow.