Atmos Workflows

Atmos Workflows

Use this skill for reusable orchestration in workflows: files: multi-step deployment flows, parallel or matrix execution, cross-component operations, preconditions, retries, typed UI/output steps, container/emulator steps, and workflow-level dependencies.

When a task is primarily about shared step fields (type, working_directory, env, output, retry, script, workdir, or hook with: payloads), also load atmos-steps.

For full workflow syntax, read references/workflow-syntax.md.

Quick Shape

workflows:
  deploy-network:
    description: Deploy network components
    stack: plat-ue2-dev
    steps:
      - type: atmos
        command: terraform deploy vpc
      - type: atmos
        command: terraform deploy dns

atmos workflow deploy-network
atmos workflow deploy-network --stack plat-ue2-prod

Discovery

Workflow files live under workflows.base_path in atmos.yaml.

workflows:
  base_path: stacks/workflows

When --file is omitted, Atmos scans workflow files and runs the workflow if exactly one match is found. Use --file for ambiguous workflow names.

Step Type Guidance

Use native step types when they express the intent directly:

Shell is appropriate for short glue, terminal-native tools, or checked-in scripts. Large inline shell blocks with loops, sleeps, formatting, CI metadata, or hand-rolled parallelism should usually be replaced by native workflow steps.

Conditions

when uses built-in predicates or CEL expressions:

steps:
  - name: prod-only
    type: shell
    command: ./scripts/check-prod.sh
    when: !cel 'stack == "prod" && ci'

Built-in predicate keywords include ci, local, always, never, success, and failure. Use !cel when a condition should be evaluated as CEL rather than treated as a predicate keyword.

when: manual is not an Atmos workflow predicate. For approvals, use a plan/apply split and CI environment protection rules.

Preconditions

require and assert verify required tools, files, dirs, environment variables, commands, or HTTP resources before continuing. They do not install anything.

steps:
  - type: require
    tools:
      - terraform
    files:
      - atmos.yaml

Route tool installation to atmos-toolchain.

Parallel and Matrix

Use parallel for independent steps:

steps:
  - type: parallel
    max_concurrency: 4
    fail:
      mode: wait_all
    steps:
      - type: atmos
        command: terraform plan vpc
      - type: atmos
        command: terraform plan dns

Use matrix when the workflow expands axes into repeated steps.

Dependencies

Declare workflow tool dependencies in the workflow or step context:

workflows:
  scan:
    dependencies:
      tools:
        checkov: "latest"
    steps:
      - type: shell
        command: checkov --directory .

Atmos toolchain installs and exposes declared tools for the workflow execution context.

Auth

Use identity on a workflow or step when a command needs Atmos Auth credentials:

steps:
  - type: shell
    identity: prod-readonly
    command: aws sts get-caller-identity

Route provider, identity, OIDC, assume role/root, and profile details to atmos-auth and atmos-profiles.

Routing

Guardrails

• Keep reusable orchestration in workflows, not ad hoc scripts.
• Prefer atmos terraform deploy for deployment steps so dependencies can be honored.
• Do not use sleeps for readiness if a wait, health check, or require step can express it.
• Avoid hidden state between steps; pass explicit outputs or files.