Skip to main content

Workflows

Configure where Atmos looks for workflow definition files. Workflows allow you to automate sequences of Atmos commands and other operations.

Configuration​

Workflows are configured in the workflows section:

atmos.yaml

workflows:
  # Can also be set using 'ATMOS_WORKFLOWS_BASE_PATH' ENV var, or '--workflows-dir' command-line argument
  # Supports both absolute and relative paths
  base_path: "stacks/workflows"

Configuration Options​

workflows.base_path

Base path to Atmos workflow definition files. Supports both absolute and relative paths. When base_path is set in the root configuration, this path is relative to it. Can also be set using ATMOS_WORKFLOWS_BASE_PATH environment variable or --workflows-dir command-line argument.

Directory Structure​

A typical workflows directory structure:

stacks/workflows/
├── deploy.yaml
├── destroy.yaml
├── validate.yaml
└── maintenance/
    ├── backup.yaml
    └── rotate-credentials.yaml

Example Workflow File​

stacks/workflows/deploy.yaml

workflows:
  deploy-vpc:
    description: Deploy VPC to all environments
    steps:
      - command: terraform apply vpc -s plat-ue2-dev --auto-approve
      - command: terraform apply vpc -s plat-ue2-staging --auto-approve
      - command: terraform apply vpc -s plat-ue2-prod --auto-approve

  deploy-all:
    description: Deploy all infrastructure
    steps:
      - command: workflow deploy-vpc
      - command: terraform apply eks-cluster -s plat-ue2-dev --auto-approve
      - command: terraform apply eks-cluster -s plat-ue2-staging --auto-approve
      - command: terraform apply eks-cluster -s plat-ue2-prod --auto-approve

Working Directory​

Workflows support a working_directory setting that controls where steps execute. This can be set at both the workflow level (applies to all steps) and individual step level (overrides workflow setting).

Path Resolution​

  • Absolute paths are used as-is (e.g., /tmp)
  • Relative paths are resolved against the Atmos base_path
  • The !repo-root YAML function can dynamically resolve to the git repository root

Example: Workflow-Level Working Directory​

stacks/workflows/build.yaml

workflows:
  build-all:
    description: Build from repository root
    working_directory: !repo-root
    steps:
      - command: make build
        type: shell
      - command: make test
        type: shell

All steps inherit the workflow's working_directory setting.

Example: Step-Level Override​

stacks/workflows/download.yaml

workflows:
  download-and-install:
    description: Download files to /tmp, then install from repo root
    working_directory: !repo-root
    steps:
      - command: wget https://example.com/archive.tar.gz
        working_directory: /tmp
        type: shell
      - command: tar -xzf /tmp/archive.tar.gz
        type: shell
      - command: make install
        type: shell

The first step overrides the workflow setting to run in /tmp, while subsequent steps use the workflow-level working_directory (repo root).

Example: Mixed Atmos and Shell Commands​

stacks/workflows/mixed.yaml

workflows:
  deploy-and-verify:
    description: Deploy infrastructure and run verification scripts
    steps:
      - command: terraform apply vpc
        stack: plat-ue2-dev
      - command: ./scripts/verify-vpc.sh
        working_directory: !repo-root
        type: shell
tip

Use working_directory when your workflow includes shell commands that depend on relative file paths, or when you need to run commands like terraform import directly in a component directory.

Workflow Environment Variables​

Workflows support an env map for setting environment variables. This can be set at both workflow level (applies to all steps) and step level (overrides workflow values).

workflows:
  deploy-multi-region:
    env:
      TF_LOG: INFO
    steps:
      - command: terraform apply vpc -s plat-ue2-dev --auto-approve
        env:
          AWS_REGION: us-east-2
      - command: terraform apply vpc -s plat-uw2-dev --auto-approve
        env:
          AWS_REGION: us-west-2

Precedence​

Environment variables merge in this order (later values win):

  1. System environment
  2. Global env from atmos.yaml
  3. Workflow-level env
  4. Step-level env
  5. Auth identity environment (if identity specified)

Scoping​

Each step runs as a separate subprocess. Step-level env and shell export commands only affect that step and do not persist to subsequent steps.

CLI Environment Variables​

ATMOS_WORKFLOWS_BASE_PATH
Base path to Atmos workflow definitions.

See Also​