​Flow

Flow is a container for tasks and their orchestration logic.

A Flow is the fundamental unit of orchestration in Kestra. It defines a set of tasks, their execution order, inputs, outputs, and orchestration logic.

Components of a flow

A flow organizes tasks, their inputs and outputs, error handling, and orchestration logic. It specifies what tasks run, when they run, and how they interact (sequentially, in parallel, or conditionally).

You can define a flow declaratively using a YAML file.

A flow must have:

• identifier (id)
• namespace
• list of tasks

Optionally, a flow can also have:

• inputs
• outputs
• variables
• triggers
• labels
• pluginDefaults
• errors
• finally
• retries
• sla
• concurrency
• descriptions
• disabled
• revision

Flow sample

Below is a sample flow definition. It uses tasks available in Kestra core for testing purposes, such as the Return or Log tasks, and demonstrates how to use labels, inputs, variables, triggers, and various descriptions.

id: hello-world
namespace: company.team

description: flow **documentation** in *Markdown*

labels:
  env: prod
  team: engineering

inputs:
  - id: my-value
    type: STRING
    required: false
    defaults: "default value"
    description: This input is optional.

variables:
  first: "1"
  second: "{{vars.first}} > 2"

tasks:
  - id: date
    type: io.kestra.plugin.core.debug.Return
    description: "Some tasks **documentation** in *Markdown*"
    format: "A log line content with a contextual date variable {{taskrun.startDate}}"

pluginDefaults:
  - type: io.kestra.plugin.core.log.Log
    values:
      level: ERROR

Plugin defaults

Use pluginDefaults to avoid repeating common configurations across multiple tasks of the same type. This is a list of default task properties that will be applied to each task of a certain type inside your flow. Refer to the Plugin Defaults documentation for more details.

Variables

Flow-level variables define key/value pairs that tasks can access using {{ vars.key }}. Refer to the flow variables documentation for more details.

List of tasks

The most important part of a flow is the list of tasks that will be run sequentially when the flow is executed.

Disable a flow

By default, all flows are active and will execute whether or not a trigger has been set.

You can disable a flow to temporarily prevent it from running. This is useful for pausing scheduled executions, troubleshooting, or testing.

Task

A task is a single action in a flow. A task can have properties, use flow inputs and other task's outputs, perform an action, and produce an output.

There are two kinds of tasks in Kestra:

• Runnable Tasks – Perform actual work (API calls, database queries, computations). Executed by workers.
• Flowable Tasks – Control orchestration (branching, looping, parallelization). Executed by the executor, not suitable for heavy computation.

Runnable Task

Runnable Tasks handle computational work in the flow. For example, these include file system operations, API calls, database queries, etc. These tasks can be compute-intensive and are handled by workers.

By default, Kestra only includes a few Runnable Tasks. However, many of them are available as plugins, and if you use our default Docker image, plenty of them are already included.

Flowable Task

Flowable Tasks only handle flow logic (branching, grouping, parallel processing, etc.) and start new tasks. For example, the Switch task decides the next task to run based on some inputs.

A Flowable Task is handled by an executor and can be called very often. Because of that, these tasks cannot include intensive computations, unlike Runnable Tasks. Most of the common Flowable Tasks are available in the default Kestra installation.

Labels

Labels are key-value pairs that you can add to flows. Labels are used to organize flows and can be used to filter executions of any given flow from the UI.

Inputs

Inputs are strongly typed parameters provided at execution time. Can be required or optional, with default values and validation rules.

Inputs of type FILE are uploaded to Kestra's internal storage and made available for all tasks.

Flow inputs can be seen in the Overview tab of the Execution page.

Outputs

Outputs are results produced by tasks or flows. Outputs can be reused in later tasks or downloaded if stored in internal storage.

Some outputs are of a special type and are stored in Kestra's internal storage. Kestra automatically makes these outputs available for all tasks.

You can view:

• task outputs in the Outputs tab of the Execution page
• flow outputs in the Overview tab of the Execution page

If an output is a file from the internal storage, it will be available to download.

For more details on both task and flow outputs, see the Outputs page.

Revision

Every change to a flow creates a new revision. Kestra automatically manages revisions, similar to version control, and you can view them in the Revisions tab.

You can access old revisions inside the Revisions tab of the Flows page.

Triggers

Triggers are a way to start a flow from external events. For example, a trigger might initiate a flow at a scheduled time or based on external events (webhooks, file creation, message in a broker, etc.).

Flow variable expressions

Flows have a number of variable expressions giving you information about them dynamically, a few examples include:

Listeners (deprecated)

Listeners are special tasks that can listen to the current flow and launch tasks outside the flow, meaning launch tasks that are not part of the flow.

The results of listeners do not change the execution status of the flow. Listeners are mainly used to send notifications or handle special behavior outside the primary flow.

Templates (deprecated)

Templates are lists of tasks that can be shared between flows. You can define a template and call it from other flows. Templates allow you to share a list of tasks and keep them updated without changing all flows that use them.

FAQ

Where does Kestra store flows?

Flows are stored in a serialized format directly in the Kestra backend database.

The easiest way to add new flows is to add them directly from the Kestra UI. You can also use the Git Sync pattern or CI/CD integration to add flows automatically after a pull request is merged to a given Git branch.

To see how flows are represented in a file structure, you can leverage the _flows directory in the Namespace Files editor.

How to load flows at server startup?

If you want to load a given local directory of flows to be loaded into Kestra (e.g., during local development), you can use the -f or --flow-path flag when starting Kestra:

./kestra server standalone -f /path/to/flows

That path should point to a directory containing YAML files with the flow definition. These files will be loaded to the Kestra repository at startup. Kestra will make sure to add flows to the right namespace, as declared in the flow YAML definition.

For more information about the Kestra server CLI, check the Server CLI Reference section.

Can I sync a local flows directory to be continuously loaded into Kestra?

At the time of writing, there is no syncing of a flows directory to Kestra. However, we are aware of that need and we are working on a solution. You can follow up in this GitHub issue.