Skip to main content

wait

The wait step type blocks the workflow until one or more named background container services are ready. The companion wait-all step type waits for every background service started so far. Readiness reuses the service's container healthcheck, so you describe "wait until healthy" declaratively instead of hand-rolling readiness-polling scripts.

A container step with background: true starts a long-running service detached and lets the workflow continue. Use wait to gate the next step on that service becoming ready:

steps:
  - name: emulator
    type: container
    action: run
    background: true
    with:
      image: localstack/localstack
      ports:
        - host: 4566
          container: 4566
      healthcheck:
        test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
        interval: 5s
        retries: 10
        start_period: 30s

  - type: wait
    for: [emulator]

  - name: apply
    type: atmos
    command: terraform apply vpc -s dev

When the named service declares a healthcheck, Atmos already blocks until it is healthy before running the next step, so an explicit wait is most useful when you start several services and want to gate a specific point in the workflow on a subset of them.

For a background service, wait means "until the service is healthy", never "until it exits" — a long-running service never exits on its own, so its health check defines readiness.

Fields​

for
List of background service step names to wait for. Each named step must be an earlier action: run step with background: true. The wait step blocks until every named service reports healthy.

wait-all​

wait-all waits for every background service started earlier in the workflow, without naming them individually:

steps:
  - name: localstack
    type: container
    action: run
    background: true
    with:
      image: localstack/localstack
      healthcheck:
        test: ["CMD", "curl", "-f", "http://localhost:4566/_localstack/health"]
        interval: 5s
        retries: 10

  - name: registry
    type: container
    action: run
    background: true
    with:
      image: registry:2
      healthcheck:
        test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:5000/v2/"]
        interval: 5s
        retries: 10

  - type: wait-all

  - name: e2e
    type: shell
    command: ./scripts/e2e.sh

wait-all takes no for field — it blocks until all background services declared up to that point are healthy.

Readiness semantics​

  • A background service with a healthcheck is "ready" when its container reports healthy.
  • wait and wait-all block until the named (or all) services are ready, then let the workflow continue.
  • The ordinary needs field is unchanged: it expresses step ordering, not service readiness.
  • Background services are torn down with a cancel step, or automatically at workflow end.

See background services on the container step page for the full lifecycle.