Pipeline loop

View as Markdown

A pipeline loop enables automatic creation of multiple pipeline runs based on combinations of variable values. Instead of manually configuring each run with different variable values, you can define a list of values for selected variables, and Buddy will automatically generate a separate pipeline run for every combination.

Info
For automating individual actions within a pipeline, see Action Loop.

Image loading...Example of a pipeline with loop variables defined

How does it work?

A pipeline loop works as a matrix. When you define variables in the loop section:

  • Single variable: each value creates a separate pipeline run
  • Multiple variables: all combinations of values are executed

Example with two variables:

  • deployment_strategy: canary, rolling (2 values)
  • region: eu-west, us-east, ap-south (3 values)
  • Result: 2 × 3 = 6 pipeline runs (each combination is a separate run)

GUI configuration

The pipeline loop configuration is located in the Run Strategy section under the pipeline’s Workflow tab.

Image loading...Run strategy

Run Strategy

Execute — standard pipeline execution:

  • Execute pipeline runs sequentially — a new run starts only after the previous one has finished (sequential execution)
  • Execute pipeline runs in parallel — allows multiple runs of the same pipeline to be executed simultaneously

Image loading...Selecting execute pipeline mode

Loop — running pipelines in the matrix:

  • Select existing variables from the list or add new ones
  • You can provide variables in two ways:

    • Comma separated: canary, rolling
    • Line by line:
      eu-west
      us-east
      ap-south
    
Info
In the loop, you can use variables defined at the pipeline, project, or workspace level.

Below is an example of a configured Run Strategy where runs execute in parallel and two variables defined in the loop: deployment_strategy and region.

Image loading...Example Run Strategy configuration

Sequential vs parallel runs

The way runs generated by the loop are executed depends on the Execute pipeline runs setting.

Sequential execution

When you select Execute pipeline runs sequentially, the runs are executed one after another:

Image loading...Runs view with the pipeline set to Execute pipeline runs sequentially and with variables defined in the loop.

Each subsequent run starts only after the previous one has finished.

Parallel execution

When you select Execute pipeline runs in parallel, all runs start simultaneously:

Image loading...Runs view with the pipeline set to Execute pipeline runs in parallel and with variables defined in the loop.

Warning
The number of parallel runs is limited by the number of runners available in your workspace plan. Check this limit before configuring a large combination matrix.

YAML configuration

You can also configure a pipeline loop in the buddy.yml file. In the pipeline section, add the loop field with a list of variables.

Single-variable example

You can provide variable values separated by commas or on separate lines:

Variable (deployment_strategy):

canary, rolling
yaml
- pipeline: Deploy to Production
  refs:
  - :default
  events:
  - type: PUSH
  loop:
  - deployment_strategy
  resources: XLARGE
  variables:
  - key: deployment_strategy
    value: "canary, rolling"

The configuration above will create 2 pipeline runs, one for canary one for rolling

Multi-variable example

Variable 1 - deployment_strategy:

canary, rolling

Variable 2 - region:

eu-west
us-east
ap-south

Example pipeline using deployment_strategy and region variables:

yaml
- pipeline: Deploy to Production
  refs:
  - :default
  events:
  - type: PUSH
  loop:
  - deployment_strategy
  - region
  resources: XLARGE
  variables:
  - key: deployment_strategy
    value: "canary, rolling"
  - key: region
    value: |-
      eu-west
      us-east
      ap-south

This will create 6 runs:

  • canary + eu-west
  • canary + us-east
  • canary + ap-south
  • rolling + eu-west
  • rolling + us-east
  • rolling + ap-south

If each line of a looped variable is a JSON object or key=value pairs, every run gets its properties as separate variables (a SERVICE line {"NAME": "backend"} → $SERVICE_NAME, with the EXTRACT: prefix → $NAME). Learn more about property extraction.

Info
You can find more information about the YAML syntax for the pipeline loop in the documentation: YAML Schema – Pipeline loop.

Summary

Pipeline Loop automatically generates multiple pipeline runs by creating all possible combinations of selected variable values. Each combination results in a separate, independent pipeline run that can be executed sequentially or in parallel, depending on your configuration.

API

The pipeline loop is also available through the REST API. You can use the loop parameter when creating or editing a pipeline:

Last modified on Nov 6, 2026