Automate Common Workflows

Optional chapter

You've already deployed the full backend. This chapter and the ones that follow are optional — reach for them when you want to package the commands your operators run every day.

Atmos workflows combine multiple steps into a single executable unit of work. Since atmos terraform deploy --all and atmos terraform destroy --all already handle graph-backed deploy and teardown, this workflow focuses on orientation: what stacks exist, which component instances are in the selected stack, how to validate the manifests, and which commands an operator should run next.

tip

See Atmos Workflows for the full reference. Workflows and custom commands compose: you can call a custom command from a workflow, and run a workflow from a custom command.

Configure the workflows directory

In atmos.yaml, configure the workflow base path:

workflows:
  base_path: "stacks/workflows"

Add workflow manifests in the stacks/workflows folder:

Terminal

stacks/
└── workflows/
    ├── backend.yaml
    └── validation.yaml

Add an operator orientation workflow

stacks/workflows/backend.yaml

name: Backend
description: Operator workflows for exploring and running the application backend

workflows:
  operator/orient:
    description: |
      Show the stack tree, component instances, component catalog, validation
      command, and day-to-day commands an operator uses for this quick-start stack.
    steps:
      - name: stacks
        type: stage
        title: Stack import tree

      - name: show-stacks
        type: shell
        command: atmos list stacks --format tree --provenance --identity=false --process-functions=false --process-templates=false

      - name: instances
        type: stage
        title: Component instances

      - name: show-instances
        command: list instances --format tree --provenance --identity=false --process-functions=false --process-templates=false

      - name: catalog
        type: stage
        title: Component catalog

      - name: list-components
        type: spin
        title: Preparing component catalog command
        command: true

      - name: show-components
        command: list components --identity=false --process-functions=false --process-templates=false

      - name: commands
        type: stage
        title: Operator commands

      - name: validation-note
        type: markdown
        content: |
          Run `atmos validate stacks` after the sandbox is started to validate the stack manifests with runtime-backed functions enabled.

      - name: command-table
        type: table
        title: Quick-start operator commands
        columns:
          - task
          - command
        data:
          - task: Start sandbox
            command: atmos emulator up aws -s <stack>
          - task: Validate manifests
            command: atmos validate stacks
          - task: Deploy stack
            command: atmos terraform deploy --all -s <stack>
          - task: Inspect provenance
            command: atmos describe component app-config -s <stack> --provenance
          - task: Destroy stack
            command: atmos terraform destroy --all -s <stack> -auto-approve

      - name: done
        type: toast
        level: info
        content: "Use `atmos terraform deploy --all -s <stack>` and `atmos terraform destroy --all -s <stack>` for graph-backed operations."

The workflow uses newer step types:

• stage prints progress markers for the operator.
• shell runs a command exactly as written.
• spin keeps a short status step compact while it runs.
• markdown adds a short validation note without executing the validation command during a dry run.
• table shows the commands operators use next.
• toast finishes with a clear status message.

Run the workflow

Run the workflow for a stack:

atmos workflow operator/orient -f backend -s plat-ue2-dev

Use --dry-run to preview the steps without executing them:

atmos workflow operator/orient -f backend -s plat-ue2-dev --dry-run

Executing the workflow 'operator/orient' from 'stacks/workflows/backend.yaml'

Executing workflow step: stacks
Executing workflow step: atmos list stacks --format tree --provenance --identity=false --process-functions=false --process-templates=false
Executing workflow step: instances
Executing workflow step: atmos list instances --format tree --provenance --identity=false --process-functions=false --process-templates=false -s plat-ue2-dev
Executing workflow step: catalog
Executing workflow step: list-components
Executing workflow step: atmos list components --identity=false --process-functions=false --process-templates=false -s plat-ue2-dev
Executing workflow step: commands
Executing workflow step: validation-note
Executing workflow step: command-table
Executing workflow step: done

Let Atmos prompt you

For single-component Terraform commands, you can omit the component or stack in an interactive terminal and Atmos will prompt you:

atmos terraform plan app-config -s plat-ue2-dev
atmos terraform plan

For bulk workflows, keep using explicit selectors such as --all, --components, or --query.