# 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:

**File:** `atmos.yaml`

```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

**File:** `stacks/workflows/deploy.yaml`

```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

**File:** `stacks/workflows/build.yaml`

```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

**File:** `stacks/workflows/download.yaml`

```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

**File:** `stacks/workflows/mixed.yaml`

```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).

```yaml
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.

## Related Commands

## See Also

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Workflows](/workflows) — Complete guide to Atmos workflows