parallel

The parallel step type runs its child steps concurrently instead of one after another, with bounded concurrency, sibling dependencies, configurable failure behavior, and parent-owned output rendering. It turns independent checks, tests, and plans into a dependency-aware group that finishes faster while keeping output readable.

List the work under steps. Each child runs concurrently up to max_concurrency, and a child with a needs list waits for the siblings it names before it starts. Child steps must be non-interactive command steps — shell, atmos, or sleep.

steps:
  - name: checks
    type: parallel
    max_concurrency: 2
    fail:
      mode: wait_all
    output:
      mode: grouped
      order: completion
      show_summary: true
      prefix: "{{ .step.name }}"
    steps:
      - name: lint
        type: shell
        command: echo "lint started"; sleep 1; echo "lint passed"

      - name: unit
        type: shell
        command: echo "unit tests started"; sleep 1; echo "unit tests passed"

      - name: package
        type: shell
        needs: [lint, unit]
        command: echo "packaging after lint and unit"

The matrix step type shares the same scheduler, failure, and output fields, but first expands a set of axes into generated child steps.

Fields

steps

Required. List of child steps to run concurrently. Each child must be a shell, atmos, or sleep step.

max_concurrency

Maximum number of child steps to run at once. Defaults to unbounded (all eligible children start together).

fail

Failure behavior for the group. See Failure behavior.

output

How the parent renders child output. Accepts a string mode or a structured block. See Output.

Each child step may also declare needs to order it after named siblings.

needs

List of sibling step names that must complete successfully before this child starts. A child whose dependency fails or is skipped is itself skipped.

Failure behavior

fail controls what happens when a child fails:

fail:
  mode: wait_all       # wait_all (default) | fail_fast | best_effort
  max_failures: 0      # 0 (default) means no limit

mode

Failure mode:

• wait_all (default): let running children finish, skip dependents of failed children, then fail the parent if any child failed.
• fail_fast: cancel pending and running children as soon as the failure threshold is reached.
• best_effort: record failures but let the parent succeed.

max_failures

Number of child failures tolerated before fail_fast cancels the group. 0 (default) means no limit.

Output

The parent step owns rendering for the whole group so concurrent output stays readable. Set output to a string for the mode, or to a block for full control:

output:
  mode: grouped        # grouped (default) | prefixed | none
  order: completion    # completion | definition (grouped only)
  show_summary: true   # print the success/failed/skipped/canceled summary
  prefix: "{{ .step.name }}"

mode

Rendering mode:

• grouped (default): capture each child's output and print it in a labeled block once the child finishes.
• prefixed: stream child output live, prefixing every line with the child's label.
• none: suppress child output.

order

For grouped mode, the order blocks are printed: completion (as children finish) or definition (in declared order).

show_summary

Print a summary line with success, failed, skipped, and canceled counts after the group completes.

prefix

Go template for the per-child label, evaluated with the child step context (for example {{ .step.name }}).

Example

A runnable example lives in examples/parallel-steps:

atmos workflow checks -f parallel