Custom flow YAML schema

Custom flows use the flow registry v1 specification syntax. The v1 specification defines the full YAML structure, including fields like version, environment, components, prompts, routers, and flow.

Some fields in the v1 specification are restricted in custom flows. For more information, see restricted fields.

The YAML configuration also has a maximum size. For more information, see configuration size limits.

Goal values by trigger type

When you design a custom flow, the goal value depends on which trigger type starts the flow. A flow can have multiple trigger types configured, and each trigger type passes a different value as context:goal. Your flow must handle the goal format for each trigger type you configure.

For more information about trigger types, see triggers.

Components access the goal through the inputs field:

components:
  - name: "my_agent"
    type: AgentComponent
    prompt_id: "my_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - "context:goal"

Mention events

When a user mentions the flow service account in a comment, the full comment text and the resource context are passed as the goal.

The goal uses this format:

Input: <comment_text>
Context: {<resource_type> IID: <iid>}

For example, if a user writes @ai-my-flow Can you work on this? on issue #2, the goal is:

Input: @ai-my-flow Can you work on this?
Context: {Issue IID: 2}

Assign and Assign reviewer events

When the flow service account is added as an assignee or reviewer to an issue or merge request, the resource type and URL are passed as the goal:

Context:
<resource_type>: <resource_web_url>

The resource type is Issue or MergeRequest.

For example, if the flow service account is added as a reviewer to merge request !10, the goal is:

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10

Use the URL to identify the resource. Don’t use the resource type, because the same issue can appear as Issue or WorkItem, depending on the trigger.

Merge request and work item events

When a merge request or work item event triggers the flow, the resource type, URL, and action are passed as the goal:

Context:
<resource_type>: <resource_web_url>
Action: <action>

The resource type is MergeRequest or WorkItem.

The action depends on the event and the Run when selection:

The Marked ready and Merge conflict actions don’t include an action in the goal.

For example, if merge request !10 is approved, the goal is:

Context:
MergeRequest: https://gitlab.example.com/my-group/my-project/-/merge_requests/10
Action: approved

Use the URL to identify the resource. Don’t use the resource type, because the same issue can appear as Issue or WorkItem, depending on the trigger.

Pipeline events

When a pipeline event triggers the flow, the full pipeline event webhook payload is passed as the goal.

Optional top-level properties

coding_environment

The optional coding_environment property declares what kind of coding environment the flow needs when a workload starts.

Use the full value when the flow needs a checkout, so that the clone happens once, up front, instead of during the run.

If you add a value other than full or none the schema validation fails and the flow does not run.

If you don’t add the coding_environment property, the flow receives the full environment and still has repository access.

Example:

version: v1
environment: ambient
coding_environment: none
components:
  - name: "api_agent"
    type: AgentComponent
    prompt_id: "my_api_prompt"
    inputs:
      - "context:goal"
routers:
  - from: "api_agent"
    to: end
flow:
  entry_point: "api_agent"

Restricted fields

Some fields and features in the v1 specification are restricted to ensure custom flows work consistently in GitLab.

environment

The environment field supports only the ambient value in custom flows.

The chat and chat-partial values are not supported.

model in prompts

The model field inside a prompts entry is not supported.

The model is determined by the model provider configured in your group or instance settings.

AgentComponent fields

The response_schema_id and response_schema_version fields are not supported.

OneOffComponent fields

The ui_role_as field is not supported.

stop in prompt parameters

The stop field is not supported inside a params entry.

Top-level fields

The name, description, and product_group fields from the v1 specification are not supported. Custom flows reject these fields.