Action Loop

View as Markdown

The Action Loop feature allows you to automatically iterate actions based on a matrix of variable value combinations. This lets you run the same action multiple times with different parameters without having to define each action manually.

Info
For automating entire pipelines with multiple runs, see Pipeline Loop.

Loop modes

When you enable Loop in the run strategy, the configuration popup offers two tabs that decide how the iterations are generated: Variables and Times.

Variables

Select one or more variables to iterate over. Each value creates a new run. A multi-line value is split by lines; a single-line value is split by commas.

  • Single variable - the action runs once per value. For test = value1, value2 and the command echo $test, Buddy generates two runs: value1 and value2.
  • Multi-variable loop (matrix) - selecting multiple variables generates all possible combinations. For whos = my, your and animal = cat, dog, the command echo $whos $animal produces four runs (my cat, my dog, your cat, your dog).

Times

Enter a number between 1 and 1000 to repeat the run that many times. The current iteration is exposed as $BUDDY_RUN_LOOP_I, so each run can tell which pass it is on:

bash
echo $BUDDY_RUN_LOOP_I
# Run 1: 1
# Run 2: 2
# Run 3: 3
$$$$

Automatic property extraction

If a looped variable contains JSON objects or key-value pairs, Buddy automatically extracts its properties into new variables prefixed with the variable's key.

USER variable:

{"name": "Li", "age": 30}
{"name": "Bob", "age": 25}
bash
echo "$USER_name is $USER_age"
$

Output:

Li is 30
Bob is 25

The same works for key-value pairs (USER = name=Li,age=30 / name=Bob,age=25 → $USER_name, $USER_age).

To map properties directly to environment variables without the key prefix, use the EXTRACT: prefix on each value.

USER variable:

EXTRACT:{"name": "Li", "role": "admin"}
EXTRACT:{"name": "Bob", "role": "user"}
bash
echo "$name is $role"
$

Output:

Li is admin
Bob is user

Put one object per line. When the value has more than one line, it is split only by lines, so commas inside a JSON object or between key=value pairs stay in the same value.

In YAML, extraction lets a single action iterate over sets of values. The looped variable can also be defined in an environment, so a shared pipeline only references the extracted keys:

yaml
- pipeline: build-images
  actions:
  - action: "Build $IMAGES_NAME"
    type: BUILD
    loop:
    - IMAGES
    docker_image_name: buddy/localshell
    docker_image_tag: ubuntu_24.04
    commands: |-
      echo "Image: $IMAGES_NAME, port: $IMAGES_PORT"
    shell: BASH
    variables:
    - key: IMAGES
      value: |-
        {"NAME": "my/backend:1.4.0", "PORT": "8080"}
        {"NAME": "my/worker:1.4.0", "PORT": "9090"}

Output:

Image: my/backend:1.4.0, port: 8080
Image: my/worker:1.4.0, port: 9090

YAML

Both tabs use the same loop field - list variable names for the Variables mode, or provide a single number for the Times mode:

yaml
# Variable matrix - one run per value combination
loop:
- deployment_strategy
- region
yaml
# Times - repeat the run a fixed number of times
loop:
- 5

The sections below cover the variable matrix mode in detail.

In the action settings, find the RUN STRATEGY section. You'll see two options: Parallel actions and Loop. Select Loop to configure action iteration. A configuration window will appear where you can select already defined variables or add new ones.

Image loading...Action editor with RUN STRATEGY section showing Loop option

How does action loop work?

Action Loops operate on the basis of a combination matrix, they generate all possible combinations of variable values and run the action separately for each combination.

YAML configuration

Action Loops can also be configured directly in the buddy.yml file using the loop field:

yaml
- pipeline: testloop-single
  fail_on_prepare_env_warning: true
  actions:
  - action: "Test loop"
    type: BUILD
    loop:
    - environment
    docker_image_name: buddy/localshell
    docker_image_tag: ubuntu_24.04
    commands:
    - "echo \"Testing: $environment\""
    shell: BASH
    variables:
    - key: environment
      value: "staging,production"

Multi-variable example:

yaml
- pipeline: testloop_multiple
  fail_on_prepare_env_warning: true
  actions:
  - action: Test multiple variables loop
    type: BUILD
    loop:
    - whos
    - animal
    docker_image_name: buddy/localshell
    docker_image_tag: ubuntu_24.04
    commands:
    - "echo \"Owner: $whos, Pet: $animal\""
    shell: BASH
    variables:
    - key: animal
      value: "cat,dog"
    - key: whos
      value: "my,your"

Image loading...View action with set loops

Result: 4 runs (2×2)

  • Run 1: echo "Owner: my, Pet: cat"
  • Run 2: echo "Owner: my, Pet: dog"
  • Run 3: echo "Owner: your, Pet: cat"
  • Run 4: echo "Owner: your, Pet: dog"

Image loading...Detail Run action with loops

Action loop configuration

The loop field accepts an array of variable names that should be used for iteration:

yaml
    loop:
    - variable1
    - variable2
    - variable3
Info
You can find more information about the YAML syntax for the action loop in the documentation: YAML Schema - Action loop.

Practical examples

Multi-region deployment

yaml
- pipeline: "multi-region-deployment"
  actions:
  - action: "Deploy to region"
    type: "BUILD"
    docker_image_name: "buddy/localshell"
    commands:
    - "echo \"Deploying to $region with $config\""
    variables:
    - key: "region"
      value: "us-east,eu-west,asia-pacific"
      type: "VAR"
    - key: "config"
      value: "dev,prod"
      type: "VAR"
    loop:
    - "region"
    - "config"

Image loading...Action Loop - configuration example

Multi-platform build

yaml
- pipeline: "multi-platform-build"
  actions:
  - action: "Build for platform"
    type: "BUILD"
    docker_image_name: "golang:1.19"
    commands:
    - "GOOS=$os GOARCH=$arch go build -o app-$os-$arch"
    variables:
    - key: "os"
      value: "linux,windows,darwin"
      type: "VAR"
    - key: "arch"
      value: "amd64,arm64"
      type: "VAR"
    loop:
    - "os"
    - "arch"

Summary

Action Loop is an option for automating repetitive tasks. Instead of manually duplicating actions, you can use a single action with a loop that automatically generates the entire combination matrix.

Warning
Remember the resource limitations and the number of combinations that may be generated.

API

The action loop is also available through the REST API. You can use the loop parameter when creating an action:

Last modified on Nov 6, 2026