matrix

The matrix step type expands a set of axes into a Cartesian product and runs the generated child steps concurrently through the same scheduler as parallel. Use it to fan a single step template out across combinations — operating systems, versions, regions — without copying YAML.

Define the axes under matrix and a child step template under steps. Atmos generates one set of child steps per axis combination and substitutes the axis values with {{ .matrix.<axis> }}.

steps:
  - name: test-matrix
    type: matrix
    max_concurrency: 3
    fail:
      mode: wait_all
    output:
      mode: grouped
      order: definition
      show_summary: true
    matrix:
      os: [linux, darwin]
      go: ["1.22", "1.23"]
    steps:
      - name: test
        type: shell
        command: echo "testing {{ .matrix.os }} with Go {{ .matrix.go }}"

The example above expands into four generated runs (linux/darwin × 1.22/1.23), each scheduled like a parallel child.

Fields

matrix accepts the steps, max_concurrency, fail, and output fields exactly as parallel does, plus the matrix axes:

matrix

Required. Map of axis name to a list of string values. Atmos builds the Cartesian product of all axes and generates one set of child steps per combination.

steps

Required. Child step template(s) instantiated for every matrix combination. Each child must be a shell, atmos, or sleep step.

max_concurrency

Maximum number of generated child steps to run at once. Applies across all combinations. Defaults to unbounded.

fail

Failure behavior for the expanded group. See Failure behavior.

output

How the parent renders generated child output. See Output.

Templating

Each generated child can reference its combination through the matrix template namespace in command, stack, env, and timeout fields:

steps:
  - name: plan
    type: shell
    command: echo "planning {{ .matrix.region }}"

Generated steps are named after the parent and their axis values so they remain distinct in output and summaries. Steps within a single generated combination run in declared order unless they use needs to depend on a sibling.

Example

A runnable example lives in examples/parallel-steps:

atmos workflow matrix -f parallel