dependencies

The workflow-level dependencies field declares the tool versions a workflow requires, and the named commands and workflows that must complete before it runs, so Atmos can provision and order everything before any step runs.

workflows:
  validate:
    dependencies:
      tools:
        tflint: "^0.54.0"
        checkov: latest
    steps:
      - command: terraform validate vpc
      - command: tflint --recursive
        type: shell

Atmos installs missing tools and prepares PATH before running the workflow.

Workflows also install every tool listed in the project's .tool-versions file that is missing, before the first step runs, unless toolchain.install is never. A workflow dependencies.tools entry overrides the .tool-versions entry for the same tool, even when one uses a short name or alias and the other the qualified owner/repo name. Entries whose version is system, ref:..., or path:..., a bare operator such as ~>, or a tool name Atmos cannot resolve are skipped. With never, nothing is installed: workflow tools and .tool-versions tools are used only when already installed, and a missing dependencies.tools entry is an error. By default (auto), components, custom commands, and hooks install less than workflows do; see Project Defaults.

Version Values

Dependency versions support the same toolchain version forms used elsewhere in Atmos:

Value	Meaning
1.10.3	Exact version
~> 1.10.0	Compatible patch releases
^1.10.0	Compatible minor releases
latest	Latest available version

Use project-wide .tool-versions files for common tool versions and workflow dependencies for workflow-specific requirements.

Named command and workflow dependencies

dependencies.commands and dependencies.workflows declare other named custom commands and workflows that must complete before this workflow runs its own steps. They resolve and run through the same generic DAG scheduler that already powers parallel/matrix needs: and Terraform's dependencies.components — concurrent by default, like go-task's deps::

workflows:
  deploy:
    dependencies:
      workflows:
        - build                       # same file, plain name
        - name: test
          file: test.yaml              # different file, explicit
      commands: [lint]
    steps:
      - type: atmos
        command: terraform apply infra -s dev

commands

List of custom command names. Entries can be a plain string (build) or an object with flags/args overrides for a parameterized invocation. A command dependency is resolved globally — Atmos already deep-merges every atmos.d-imported command definition into one list before anything runs, so there's no file boundary to specify.

workflows

List of workflow names. A plain string (build) resolves within the same file as the workflow declaring the dependency. An object entry with file: resolves in a different file, using the exact same resolution as the CLI's atmos workflow <name> -f <file>. There is no implicit scanning of workflows.base_path to build a global namespace — a cross-file reference always names its file explicitly.

Two dependency entries that resolve to the same name and the same parameters collapse into a single execution, even if two different dependents both declare it:

# release depends on [test, lint]; both test and lint depend on build.
# build runs exactly once for the whole `atmos workflow deploy` invocation.
workflows:
  build:
    steps: [...]
  test:
    dependencies:
      workflows: [build]
    steps: [...]
  lint:
    dependencies:
      workflows: [build]
    steps: [...]
  deploy:
    dependencies:
      workflows: [test, lint]
    steps: [...]

Entries with different parameters are distinct nodes and both run:

workflows:
  release:
    dependencies:
      commands:
        - name: build
          flags: { env: dev }
        - name: build
          flags: { env: prod }
    steps: [...]

Failure propagation

By default (wait_all), a failed dependency skips everything that transitively depends on it, and the dependency graph's combined error is returned at the end. fail reuses the exact same modes parallel uses, derived from every direct dependencies.commands/dependencies.workflows entry on this workflow: best_effort wins if any direct entry sets it, else fail_fast if any direct entry sets it, else wait_all. It's a single mode for the whole dependency run, not a per-entry setting, so setting it on one entry affects how every dependency in the graph fails:

dependencies:
  workflows:
    - name: test
      fail: best_effort   # wait_all (default) | fail_fast | best_effort