Workflow file reference

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:

env0.workflow.yaml

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

env0.workflow.yaml

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:

env0.workflow.yaml

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.

env0.workflow.yaml

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.

env0.workflow.yaml

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

Use variable interpolation with the disabled property to enable partial workflow deployments based on environment variables.

Learn more: Workflow file JSON schema

Next steps

Creating a new workflow - Walk through creating and deploying a workflow end to end.
Workflow file JSON schema - Validate and auto-complete workflow files in your IDE.
Partial workflow deployment - Deploy or destroy a subset of the workflow graph.

GET STARTED

ENVIRONMENTS & DEPLOYMENTS

TEMPLATES & IaC TOOLS

PLATFORM CONFIGURATION

SELF-HOSTED AGENTS

CLOUD MANAGEMENT

GOVERNANCE & POLICIES

ACCESS & IDENTITY

SECURITY & COMPLIANCE

INTEGRATIONS & DEVELOPER TOOLS

BILLING & SUPPORT

File Structure

Settings

Sub-Environment Properties

Core Properties

Optional Properties

VCS Configuration

VCS Authentication Properties

VCS Provider Flags

IaC Version Properties

CloudFormation Properties

Helm Properties

Examples

Simple Workflow with Template References

Workflow with Inline VCS Configuration

Mixed Workflow with Settings

Workflow with Variable Interpolation

Next steps

​File Structure

​Settings

​Sub-Environment Properties

​Core Properties

​Optional Properties

​VCS Configuration

​VCS Authentication Properties

​VCS Provider Flags

​IaC Version Properties

​CloudFormation Properties

​Helm Properties

​Examples

​Simple Workflow with Template References

​Workflow with Inline VCS Configuration

​Mixed Workflow with Settings

​Workflow with Variable Interpolation

​Next steps

File Structure

Settings

Sub-Environment Properties

Core Properties

Optional Properties

VCS Configuration

VCS Authentication Properties

VCS Provider Flags

IaC Version Properties

CloudFormation Properties

Helm Properties

Examples

Simple Workflow with Template References

Workflow with Inline VCS Configuration

Mixed Workflow with Settings

Workflow with Variable Interpolation

Next steps