> ## Documentation Index
> Fetch the complete documentation index at: https://docs.envzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow file reference

> Complete reference for the env0.workflow.yaml file schema, covering environments, sub-environment dependencies, settings, and requiresApproval options.

This page provides a complete reference for the `env0.workflow.yaml` (or `.yml`) file used to define env zero Workflows.

## File Structure

The workflow file has two main sections:

* **`environments`** (required) - Defines the sub-environments in the workflow
* **`settings`** (optional) - Global workflow settings

Example:

```yaml env0.workflow.yaml theme={null}
settings:
  environmentRemovalStrategy: detach # or destroy

environments:
  my-environment:
    name: "My Environment"
    templateName: "my-template"
    # ... additional configuration
```

## Settings

Global settings that apply to the entire workflow.

`environmentRemovalStrategy` (string) controls what happens when a sub-environment is removed from the workflow file.

* Default: `detach`
* `detach` - The environment is detached but not destroyed.
* `destroy` - The environment is destroyed after you deploy the updated workflow.

## Sub-Environment Properties

Each sub-environment is defined as a key-value pair under `environments`. The key is a unique alias for the sub-environment.

### Core Properties

| Property | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Display name shown in the env zero UI. |
| `templateName` | `string` | No\* | Name of an existing env zero template. Cannot be used with `vcs`. |
| `vcs` | `object` | No\* | Inline VCS configuration. Cannot be used with `templateName`. |

**\* Either `templateName` or `vcs` must be specified, but not both.**

### Optional Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `needs` | `array` | `[]` | List of sub-environment aliases that must deploy before this one. |
| `revision` | `string` | - | Git revision (branch, tag, or commit SHA) to use. |
| `workspace` | `string` | - | For Terraform/OpenTofu, sets the workspace name. For Helm, sets the release name. For Pulumi/CloudFormation, sets the stack name. |
| `requiresApproval` | `boolean` | `false` | If `true`, deployment requires manual approval before proceeding. |
| `disabled` | `boolean` or `string` | `false` | If `true` or `"true"`, this sub-environment is skipped during deployment. Supports variable interpolation. |

If you also manage the workflow environment with the env zero Terraform provider, see [Terraform provider settings for sub-environments](/guides/admin-guide/workflows/terraform-provider-sub-environment-settings) for how `requiresApproval`, `workspace`, and `revision` interact with the `sub_environment_configuration` block.

## VCS Configuration

If you want to use your code directly without creating a template for it first, you can use the `vcs` object with the following properties:

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | `string` | Yes | - | IaC type. Options: `terraform`, `opentofu`, `terragrunt`, `pulumi`, `k8s`, `cloudformation`, `helm`, `ansible`. |
| `repository` | `string` | Yes | - | Git repository URL (HTTPS or SSH). |
| `path` | `string` | No | `""` | Path within the repository where IaC code is located. |
| `revision` | `string` | No | - | Git revision (branch, tag, or commit) to use. |

### VCS Authentication Properties

| Property | Type | Description |
| - | - | - |
| `tokenId` | `string` | ID of a stored VCS token for authentication. |
| `tokenName` | `string` | Display name of the VCS token. |
| `sshKeys` | `array` | SSH keys for repository authentication. Each item requires `id` and `name`. |
| `githubInstallationId` | `number` | GitHub App installation ID. |
| `bitbucketClientKey` | `string` | Bitbucket client key for Bitbucket Cloud. |
| `vcsConnectionId` | `string` | VCS connection ID for unified VCS integration. |

### VCS Provider Flags

| Property | Type | Default | Description |
| - | - | - | - |
| `isGitLab` | `boolean` | `false` | Set to `true` for GitLab.com repositories. |
| `isGitLabEnterprise` | `boolean` | `false` | Set to `true` for GitLab Enterprise/self-hosted. |
| `isGitHubEnterprise` | `boolean` | `false` | Set to `true` for GitHub Enterprise. |
| `isBitbucketServer` | `boolean` | `false` | Set to `true` for Bitbucket Server/Data Center. |
| `isAzureDevOps` | `boolean` | `false` | Set to `true` for Azure DevOps. |

### IaC Version Properties

| Property | Type | Description |
| - | - | - |
| `terraformVersion` | `string` | Terraform version. Use a specific version (e.g., `1.5.7`) or `RESOLVE_FROM_TERRAFORM_CODE`. |
| `opentofuVersion` | `string` | OpenTofu version. Use a specific version (e.g., `1.6.0`). |
| `terragruntVersion` | `string` | Terragrunt version (e.g., `0.54.0`). |
| `terragruntTfBinary` | `string` | Underlying binary for Terragrunt: `terraform` (default) or `opentofu`. |
| `pulumiVersion` | `string` | Pulumi version (e.g., `3.100.0`). |
| `ansibleVersion` | `string` | Ansible version (e.g., `2.15.0`). |

### CloudFormation Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `helmChartName` | `string` | - | Helm chart name when using a Helm repository. |
| `isHelmRepository` | `boolean` | `false` | Set to `true` if the repository is a Helm chart repository. |

### Helm Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `helmChartName` | `string` | - | Helm chart name when using a Helm repository. |
| `isHelmRepository` | `boolean` | `false` | Set to `true` if the repository is a Helm chart repository. |

## Examples

### Simple Workflow with Template References

A basic workflow using pre-defined templates with dependencies.

```yaml env0.workflow.yaml theme={null}
environments:
  database:
    name: "PostgreSQL Database"
    templateName: "aws-rds-postgres"
    workspace: "production"

  api:
    name: "API Service"
    templateName: "kubernetes-deployment"
    needs:
      - database
    requiresApproval: true
```

### Workflow with Inline VCS Configuration

Define IaC source directly without creating separate templates:

```yaml env0.workflow.yaml theme={null}
environments:
  networking:
    name: "VPC and Networking"
    vcs:
      type: terraform
      repository: "https://github.com/myorg/infrastructure"
      path: "terraform/networking"
      terraformVersion: "1.5.7"

  compute:
    name: "EC2 Instances"
    vcs:
      type: terraform
      repository: "git@github.com:myorg/infrastructure.git"
      path: "terraform/compute"
      terraformVersion: "RESOLVE_FROM_TERRAFORM_CODE"
      sshKeys:
        - id: "ssh-key-123"
          name: "Deploy Key"
    needs:
      - networking
```

### Mixed Workflow with Settings

Combine template references and inline VCS with global settings.

```yaml env0.workflow.yaml theme={null}
settings:
  environmentRemovalStrategy: detach

environments:
  infra:
    name: "Base Infrastructure"
    templateName: "terraform-aws-base"
    revision: "v2.0.0"

  app:
    name: "Application"
    vcs:
      type: helm
      repository: "https://github.com/myorg/helm-charts"
      path: "charts/myapp"
    needs:
      - infra

  monitoring:
    name: "Monitoring Stack"
    templateName: "prometheus-grafana"
    needs:
      - infra
    disabled: false
```

### Workflow with Variable Interpolation

Use environment variables to conditionally disable sub-environments.

```yaml env0.workflow.yaml theme={null}
environments:
  vpc:
    name: "VPC and Network"
    templateName: "VPC"

  db:
    name: "Database"
    templateName: "DB"
    requiresApproval: true
    needs:
      - vpc

  eks:
    name: "EKS Cluster"
    templateName: "EKS"
    needs:
      - vpc

  billing-service:
    name: "Billing Service"
    templateName: "Billing Service"
    disabled: ${DISABLE_BILLING_SERVICE}
    needs:
      - db
      - eks

  config-service:
    name: "Configuration Service"
    templateName: "Configuration Service"
    revision: feature-branch
    disabled: ${DISABLE_CONFIG_SERVICE}
    needs:
      - db
      - eks
```

<Tip>
  Use variable interpolation with the `disabled` property to enable partial
  workflow deployments based on environment variables.
</Tip>

Learn more: [Workflow file JSON schema](/guides/admin-guide/workflows/workflow-file-json-schema)

## Next steps

* [Creating a new workflow](/guides/admin-guide/workflows/create-a-new-workflow) - Walk through creating and deploying a workflow end to end.
* [Workflow file JSON schema](/guides/admin-guide/workflows/workflow-file-json-schema) - Validate and auto-complete workflow files in your IDE.
* [Partial workflow deployment](/guides/admin-guide/workflows/workflow-partial-deployment) - Deploy or destroy a subset of the workflow graph.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.