Automations

An automation determines when a flow or external agent runs. An automation cannot be created for a custom agent or foundational agent.

An automation is one of two kinds:

• An event-based automation runs a flow when something happens in the project, for example when someone mentions the service account or a pipeline fails.
• A scheduled automation runs a flow at a recurring time, for example every weekday at 9:00 AM.

To run the same flow on an event and on a schedule, create two automations.

View automations

Prerequisites:

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

To view the automations for a project:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.

Event-based automations

An event-based automation runs a flow when one of its conditions occurs, for example when someone assigns the service account as a reviewer. An automation can have several event conditions.

Create an event-based automation

Prerequisites:

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

To create an automation:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.
3. Select New automation.
4. In Name, enter a name for the automation.
5. From the Runs with dropdown list, select one of the following:
   • A flow or external agent enabled in the project. If the Developer Flow is enabled, it is selected by default.
   • Configuration file. Then, in Configuration path, enter the path to the flow configuration file (for example, .gitlab/duo/flows/claude.yaml). From the Service account dropdown list, select a user to be the composite identity. To view this option, the ai_catalog_create_third_party_flows flag must be enabled.
6. If the Instructions field is shown, enter what the flow must do. For the Developer Flow, instructions are required. For more information, see Add instructions.
7. Under Runs when, if a schedule is open, select Cancel. A new automation starts with a schedule when the flow can run on a schedule.
8. For each event that should start the automation:
   1. Select Add trigger > On an event.
   2. From the Select an event dropdown list, select an event type.
   3. If the event type has actions, from the Run when dropdown list, select one or more actions.
   4. Select Add event.
9. Select Create.

The automation now appears in AI > Automations.

Event types

Work item type IDs

In the GraphQL API, the filter argument of the aiFlowTriggerCreate and aiFlowTriggerUpdate mutations sets the work item type filter with a work_item_type_id rule. The rule uses the in operator to run the flow only for the listed types, or the not_in operator to run the flow for all other types. The value is a list of work item type IDs. The IDs are integers, for example 5. GitLab rejects a string such as "5". For example, this filter runs the flow only when the status of a task changes to In dev:

{
  "work_item": {
    "rules": [
      { "field": "action", "operator": "in", "value": ["status_changed"] },
      { "field": "status.name", "operator": "in", "value": ["In dev"] },
      { "field": "work_item_type_id", "operator": "in", "value": [5] }
    ]
  }
}

The default work item types have the same ID on every GitLab instance:

Custom work item types have other IDs. To find the ID of a type, query the workItemTypes field of the project. The ID is the number at the end of the id of the type.

The automation form shows and changes only in rules. For a not_in rule, the Type dropdown list shows Any type, and the form keeps the rule. If you change the types in the form, the form replaces the not_in rule.

Automations for foundational flows

An automation runs only when its foundational flow is turned on for your group or project. For more information, see turn foundational flows on or off.

Foundational flows can start in the following ways:

• Default automations that GitLab adds when you turn on the flow.
• Automations that you create for events the flow supports.
• Another way, such as when a security scan finishes. These flows don’t use automations, so you don’t see them listed in AI > Automations.

For details about how to start each flow, see the individual foundational flow documentation.

Change the work item when the session finishes

An automation can change a work item after the session that the automation started finishes. Use this to move a work item to the next stage of your process, with no human action between the stages.

You can set one or both of these settings:

• Set work item status: GitLab sets the work item to this status.
• Mark merge requests as ready: GitLab marks the draft merge requests that the session created as ready. If automatic reviews are on, GitLab then adds GitLab Duo Code Review as a reviewer.

If you set both, GitLab marks the merge requests as ready first. If a merge request stays a draft, GitLab does not set the status.

Prerequisites:

• You must have the Maintainer or Owner role for the project.
• The automation must have a Work item condition with Status changed as its only action, and at least one status. Until the condition meets these requirements, the settings are not available.

To change the work item when the session finishes:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.
3. For the automation you want to change, select More actions ( ) > Edit automation.
4. In the Conditions section, for the Work item condition, select Edit event ( ).
5. From the Run when dropdown list, select only Status changed.
6. From the Status dropdown list, select one or more statuses, then select Save.
7. Under When the session finishes, set one or both:
   • From the Set work item status dropdown list, select a status.
   • Select the Mark merge requests as ready checkbox.
8. Select Save changes.

If you later add the Created action, remove the last status, or remove the Work item condition, GitLab clears the settings. If you change the types so that they do not have the status of Set work item status, GitLab clears that status.

When GitLab applies the settings

GitLab applies the settings only when all of these conditions are true:

• The session has the finished status. A stopped session, a failed session, or a session that waits for input changes nothing.
• The automation is turned on.
• A work item event started the session.
• A human user started this session, or the first session of its chain, in one of these ways:
  • With a Mention, Assign, or Work item event.
  • In a session with a GitLab Duo agent, such as a GitLab Duo Agentic Chat session. For example, the user triggers a flow with a slash command.
• The work item still has one of the statuses of the automation. If the status changes to a status that the automation does not run on while the session runs, GitLab changes nothing. This also applies when the flow sets the status of its own work item.
• The service account of the session enforces composite identity.
• The service account and the user who started the session can both update the work item and the merge requests.

GitLab does not set a status that the work item type does not have.

Chain automations

GitLab writes the changes as the composite identity of the session. For this reason, GitLab treats the status change as an event that a flow caused. The status change can start another automation that runs on the new status. The finished session becomes the parent of the next session, inside the chain depth and breadth limits.

To keep a human decision between two stages, set the status to one that no automation runs on, for example Plan ready. A user then moves the work item to the status that starts the next stage.

The following table shows two automations that move a work item through three statuses with no human action between the stages.

Known issues

• A session can finish without the work done. For example, GitLab Duo Developer can decide that no code change is necessary and open no merge request. GitLab still sets the status. If your flow can stop early, make it end as failed or as waiting for input. GitLab then does not set the status.
• If the status that the automation sets is also one of the statuses that the automation runs on, the change can start the automation again. The form shows a warning for this configuration.

Actions that don’t initiate an automation

All 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 an automation.

This restriction applies to all event types. For example, a flow cannot trigger another flow by mentioning the service account in a comment. The status change from the settings of an automation is an exception. For more information, see chain automations.

The Merged action of the Merge request event type is also an exception. The automation checks the author of the merge request, not the user who merges. For a merge request that a flow creates, the author is the human user of the composite identity. For example:

• When a bot user or a service account user merges a merge request that a human user authored, the automation runs.
• When a flow merges the merge request, the automation does not run, even when a human user authored it.
• When a non-human user authored the merge request, the automation does not run.

An automation with the Work item event type and the Created action also does not run when:

• The work item is imported from another GitLab instance or another tool, such as GitHub or Jira.
• The work item is created from an email to Service Desk.

Scheduled automations

A scheduled automation runs a flow at a recurring time. Use a scheduled automation for work that does not start from an event, such as a weekly summary of stale issues. The flow receives no merge request or work item, so use instructions to tell the flow what to do on each run.

Scheduled automations have these limits:

• A scheduled automation has one schedule.
• You can create scheduled automations only in projects, not in groups.
• By default, a project can have up to 100 scheduled automations.

Service account for scheduled automations

When you create a scheduled automation, GitLab creates a service account for that automation only. The account name starts with Duo Scheduled, followed by the project path and the automation description. GitLab adds the account to the project with the same role as the service account of the flow. GitLab does not assign the Owner role to the account, and a run fails if the account has it.

A scheduled run does not use composite identity, so the role of the service account is the only limit on what the flow can do. GitLab adds the service account to the project where you create the automation. A scheduled run can access another project only if someone adds the service account to that project as well. For more information, see security threats in GitLab Duo Agent Platform.

The role of the account follows the role of the service account of the flow:

• Before each run, if the flow account has a lower role, GitLab lowers the role of the automation account to match. If GitLab cannot lower the role, the run fails.
• If the flow account has a higher role, GitLab raises the role of the automation account only when someone who can assign that role edits the automation.

Create a scheduled automation

Prerequisites:

• You must have the Maintainer or Owner role for the project.
• Your role for the project must be equal to or higher than the role of the service account of the flow.
• You must have permission to create service accounts and to add members to the project.
• The project must belong to a group, and the group must not prevent adding members to projects.
• Experiment and beta features must be turned on.
• Scheduled automations must be turned on for the project, group, or instance.
• A custom flow from the AI Catalog or the Developer Flow must be enabled in the project. Other foundational flows, external agents, and flows that use a configuration file cannot run on a schedule.

To change the flow of an existing scheduled automation:

• Your role for the project must be equal to or higher than the role of the automation’s service account.
• You must have permission to add members to the project.
• The new flow must be a custom flow from the AI Catalog or the Developer Flow.

You do not need these permissions to change the schedule, name, or instructions.

To create a scheduled automation:

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

2. In the left sidebar, select AI > Automations.

3. Select New automation.

4. In Name, enter a name for the automation.

5. From the Runs with dropdown list, select the flow.

6. If the Instructions field is shown, enter what the flow must do on each run. For the Developer Flow, instructions are required.

7. Under Runs when, a new automation starts with a weekly schedule, with a day and time already selected. If no schedule is open, select Add trigger > On a schedule.

8. From the frequency dropdown list, select how often the flow runs. Depending on the frequency, select when the flow runs:

   Frequency	What you select
   Every 15 minutes	None
   Every 30 minutes	None
   Hourly	The minute past the hour.
   Daily	The hour and minute.
   Weekdays	The hour and minute, Monday through Friday.
   Weekly	The day of the week, hour, and minute.
   Monthly	The day of the month, from 1 to 28, and the hour and minute.

   Hours use the 24-hour clock. Minutes are in 15-minute steps.

9. Optional. For frequencies other than every 15 or 30 minutes, to change the time zone, select Change, then select a time zone. The default is the time zone of your profile, or of your browser if your profile has none.

10. Select Add schedule.

11. Select Create.

The flow might run a few minutes after the scheduled time, because GitLab spreads scheduled runs to distribute load.

When a scheduled run fails

When a scheduled run fails, GitLab emails the users with the Owner or Maintainer role for the project. If the project has no users with these roles, GitLab emails the users with the Owner or Maintainer role for the group. A run fails if, for example, the service account is missing from the project, is inactive, has the Owner role, or has a role that GitLab cannot lower to match the flow.

After three consecutive failures, GitLab deactivates the schedule and sends a deactivation email instead of a failure email. A successful run resets the count.

GitLab skips a scheduled run, and does not count a failure, when:

• The automation is turned off.
• Experiment and beta features are turned off for the group or instance.
• Scheduled automations are turned off for the project, group, or instance.
• Flow execution is turned off.
• The namespace has no GitLab Credits left.
• The project is archived or scheduled for deletion.

To resume a deactivated schedule, fix the cause in the email, then set active to true with the aiFlowScheduleUpdate GraphQL mutation. To get the ID of the schedule, query the flowSchedules field of the automation. Reactivation does not reset the failure count, so one more failed run deactivates the schedule again. The automation toggle does not reactivate a schedule. After GitLab deactivates the schedule, the automation stays turned on, but the flow does not run.

Turn scheduled automations on or off

Scheduled automations are turned on by default. When you turn off scheduled automations, existing schedules stop running but GitLab keeps them. Runs that are in progress continue. You cannot add a schedule to an automation while scheduled automations are turned off. When you turn scheduled automations back on, schedules resume at their next scheduled time. GitLab does not make up the runs that it skipped.

To turn scheduled automations on or off, flow execution must be turned on. When scheduled automations are turned off for a group or the instance, subgroups and projects cannot turn them on.

Add instructions

Instructions are text that tells the flow what to do when the automation runs. An automation has one set of instructions, which applies to every event and schedule in the automation. To run the same flow with different instructions, create another automation.

Prerequisites:

• You must have the Maintainer or Owner role for the project.
• The automation must run a custom flow, an external agent, the Developer Flow, or a configuration file. For other flows, the Instructions field does not appear. For the Developer Flow, instructions are required.

To add instructions to an existing automation:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.
3. For the automation you want to change, select More actions ( ) > Edit automation.
4. In the Instructions field, enter the instructions. Use 4096 characters or fewer.
5. Select Save changes.

You can also add instructions when you create an event-based automation, create a scheduled automation, or enable a flow.

Write instructions

The instructions go in front of the information that the event supplies. The instructions never replace that information. Do not repeat that information in the instructions.

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.
• For a schedule, a context block with the web address of the project.

To write instructions that get 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 instructions.

Edit an automation

Prerequisites:

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

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.
3. For the automation you want to change, select More actions ( ) > Edit automation.
4. Make the changes and select Save changes.

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

Turn an automation on or off

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

Prerequisites:

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

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

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

Delete an automation

Prerequisites:

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

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select AI > Automations.
3. For the automation you want to delete, select More actions ( ) > Delete automation.
4. On the confirmation dialog, select OK.

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

GitLab Credits consumption for triggered flows

A flow started by an automation runs as a service account. The flow’s usage is billed to the namespace, not to the user who performed the triggering action.

For example, an automation 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 automation runs the flow as the configured service account, and the usage is billed to the namespace rather than to the third approver.

This billing applies to every event type, including a pipeline state change, a work item status change, a mention, or a schedule.

For more information, see billing subjects for credit usage.

Troubleshooting

Error: Event types contains event types not supported

When you create or edit an automation for a foundational flow, you might get this error:

Event types contains event types not supported by this foundational flow

The automation includes an event type that the flow does not accept. To resolve this error, check the flow’s documentation for the events it supports, then do one of the following:

• If the flow uses automations, edit the automation to remove the events the flow does not support. For example, Fix CI/CD Pipeline accepts only Pipeline events.
• If the flow starts another way, delete the automation because the flow doesn’t need one. For example, SAST False Positive Detection runs after a security scan.

Service account shows No triggers for this event

When you assign a service account to a merge request or request a review from it, the service account might be disabled with the message No triggers for this event. In mention autocomplete, a service account without an automation for the Mention event doesn’t appear. In each case, the project has no automation for that service account and event:

• The assignee menu requires Assign.
• The reviewer menu requires Assign reviewer.
• Mention autocomplete requires Mention.

To resolve this issue:

1. In your project, select AI > Automations.
2. Check for an automation that uses the service account and the event you want.
3. Check the flow’s documentation to confirm that the flow supports that event.
4. If the flow supports the event, create or edit an automation to include it. Otherwise, use the method described in the flow’s documentation.

An event that you can save in an automation is not necessarily an event the flow can run. For example, Developer cannot run from Pipeline events. Use a supported event rather than adding an event only to make a service account selectable.

Error: Event types cannot combine autonomous event types

When you save an automation that has both a schedule and an event, you might get this error:

Event types cannot combine autonomous event types (scheduled) with other event types. Create a separate automation for them.

An automation with a schedule cannot have event conditions, and you cannot save the automation until you remove one of them. To resolve this error, remove the event and create a separate automation for it.

Warning: Flow enabled without an automation

When you enable a flow and add a schedule at the same time, GitLab might enable the flow without the automation and show this warning:

The scheduled automation was not created. <reason>

This warning occurs when GitLab cannot create a service account for the scheduled automation. The flow is still turned on, but without a schedule.

The <reason> in the warning message explains the cause.

Common causes are:

• You do not have permission to create a service account in the project, or to add members to the project.
• The project’s group prevents adding members to projects.
• The service account of the flow has the Owner role, or a role higher than you can assign.

To resolve this warning, address the cause noted in the warning message and create a scheduled automation for the flow again.

For the full list of requirements, see the prerequisites for creating a scheduled automation.

Investigate scheduled run outcomes

Prerequisites:

• You must have access to the instance logs.

Ai::RunFlowScheduleWorker records one line for every scheduled run it finishes. Use these lines when the schedule UI shows a result you cannot explain, or when a run produced no session at all.

Where to read the lines depends on your offering:

• On GitLab Self-Managed, search application_json.log.
• On GitLab Dedicated, search the application logs in your Amazon S3 bucket.

The line includes these fields:

Runs that GitLab skips, which do not count as failures, use these reasons:

A failed run counts toward the three consecutive failures that deactivate a schedule. GitLab assigns these reasons:

When the flow names its own reason, GitLab logs that instead. Common values are unsupported_event when the flow has no goal template for a schedule, autonomous_trigger_source_not_permitted when the automation mixes a schedule with other event types, and run_not_eligible when a foundational flow declined the run. Read error_message on the same line for the detail.

To check whether a due schedule was picked up at all, look for the worker’s own Sidekiq job instead. Filter sidekiq.log on json.class: "Ai::RunFlowScheduleWorker", then match json.correlation_id to the outcome line.