workflows

Atmos workflows are versioned runbooks for infrastructure operations. Use them to turn repeatable deployment, validation, maintenance, and release procedures into YAML that runs the same way on a laptop, in CI, or from a Git hook.

Workflow manifests live under the directory configured by workflows.base_path in atmos.yaml. Each manifest has a top-level workflows map. Each key under that map is a named workflow that Atmos can run with atmos workflow.

stacks/workflows/deploy.yaml

workflows:
  deploy-platform:
    description: Deploy the platform foundation in dependency order.
    stack: plat-ue2-prod
    show:
      header: true
      count: true
    steps:
      - command: terraform apply vpc -auto-approve
      - command: terraform apply eks/cluster -auto-approve
      - command: terraform apply eks/alb-controller -auto-approve

Run it by name:

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

Why Workflows

Workflows are useful when an operation has more than one step, has to run in a specific order, or needs the same guardrails every time:

• Multi-component deploys that apply networking, clusters, services, and verification in order.
• Validation flows that run Terraform, policy checks, smoke tests, and formatting checks as one command.
• Maintenance runbooks for backups, rotation, cleanup, or repair tasks.
• Guided release flows that collect input, confirm production changes, and render status as the run progresses.

Because workflows are YAML, they are reviewable, reusable, and easy to run from CI without turning operational process into one-off shell scripts.

Manifest Shape

Each workflow file must define a workflows map:

workflows:
  <workflow-name>:
    description: <description>
    steps: []

The keys under workflows are workflow names. Each value is a single workflow object.

File Discovery

Atmos searches the directory configured by workflows.base_path for YAML files. The path is configured in atmos.yaml:

atmos.yaml

workflows:
  base_path: stacks/workflows

When a workflow name is unique, the file can be omitted:

atmos workflow eks-up --stack tenant1-ue2-dev

Use --file when multiple files contain the same workflow name or when a script should be explicit:

atmos workflow eks-up --file deploy --stack tenant1-ue2-dev

The --file value is relative to workflows.base_path; the .yaml extension is optional.

Workflows vs Custom Commands

Use	Workflows	Custom commands
Configuration location	Workflow manifests under workflows.base_path	The commands section in atmos.yaml
How users run them	atmos workflow <name>	atmos <command>
Best for	Versioned runbooks and multi-step orchestration	Extending the CLI with team-specific commands, arguments, and flags
Step support	Uses workflow steps and step types	Can use the same step types in command steps
Composition	Can call custom commands	Can call workflows

Use workflows when the operation is an orchestration unit: deploy these components, validate this stack, rotate this credential, run this release sequence. Use custom commands when you want a first-class Atmos command with its own arguments, flags, help text, and CLI completion behavior.

Common Patterns

Multi-component deploy

workflows:
  deploy-networking:
    description: Deploy shared networking components.
    steps:
      - command: terraform apply vpc -s plat-ue2-prod -auto-approve
      - command: terraform apply dns -s plat-ue2-prod -auto-approve
      - command: terraform apply transit-gateway -s plat-ue2-prod -auto-approve

Validation gate

workflows:
  validate-platform:
    description: Run checks before a platform release.
    steps:
      - command: terraform validate vpc -s plat-ue2-prod
      - type: shell
        command: make policy-check
        working_directory: !repo-root
      - type: toast
        level: success
        content: Validation complete.

Guided release flow

workflows:
  release:
    description: Collect release input, confirm, then deploy.
    steps:
      - name: version
        type: input
        prompt: Release version
      - name: confirm
        type: confirm
        prompt: "Release {{ .steps.version.value }} to production?"
      - command: workflow deploy-platform

Related Commands

atmos workflow

Run a workflow or open the interactive workflow UI

atmos list workflows

List available workflow names

atmos describe workflows

Inspect workflow definitions and source files

Custom commands

Define first-class Atmos commands in atmos.yaml

Related

• workflow describes one named entry under workflows.
• steps describes the workflow's ordered step array.
• CLI workflow configuration describes the atmos.yaml workflows.base_path setting.

Older section links now point to YAML-shaped pages:

• steps type
• steps retry
• workflow container
• steps identity