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

# Creating a new workflow

> Create an env zero workflow using env0.workflow.yaml, covering dependency definitions, approval priority order, and multi-environment workflow setup.

To set up a Workflow, follow these steps:

env zero relies on a file named **env0.workflow\.yaml** (or **env0.workflow\.yml**) to describe the dependencies and configuration of the sub-environments in your workflow.

For the complete schema reference, see [Workflow file reference](https://docs.envzero.com/guides/admin-guide/workflows/workflow-file-reference.md).

## Approval Priority Order

When multiple approval settings exist, approvals are evaluated in the following priority:

1. [ENV0\_REQUIRES\_APPROVAL](https://docs.envzero.com/guides/admin-guide/custom-flows.md#forcing-manual-approvals) environment variable
2. Approval policy (always evaluated if defined)
3. Value from the UI or API request
4. Value from the workflow `requiresApproval` field
5. The sub-environment's saved approval setting, which env zero updates from the result of steps 3 and 4 on every deploy or destroy run, and on create.

If you also manage the workflow environment with the Terraform provider, see [Terraform provider settings for sub-environments](https://docs.envzero.com/guides/admin-guide/workflows/terraform-provider-sub-environment-settings.md) for which configuration surface wins for each setting.

If the project has [Skip apply when plan has no changes](https://docs.envzero.com/guides/policies-governance/deployment-controls.md#skip-apply-when-plan-has-no-changes) enabled, a sub-environment whose plan reports no resource changes finishes without waiting for approval, including when a custom flow set `ENV0_REQUIRES_APPROVAL=true`. An approval policy returning a pending result still holds the sub-environment for approval.

## Example Configuration

```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"
    vcs:
      type: terraform
      terraformVersion: "1.5.7"
      repository: "https://github.com/env0/templates"
      path: "aws/hello-world"
      githubInstallationId: 123456789
    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
```

### Using Environment Variables in Workflow Fields

You can use `${...}` syntax to interpolate environment variables into workflow fields.

In the example above:

* `DISABLE_BILLING_SERVICE` controls whether the `billing-service` environment is disabled.
* `DISABLE_CONFIG_SERVICE` controls whether the `config-service` environment is disabled.

When these variables are set to `true` (for example, in your environment or via env zero variables), the corresponding sub-environment is skipped during deployment.

## Environment Removal Strategy

By default, removing an environment from the workflow file leaves it detached but not destroyed.

To automatically run a "destroy" process on environments that were removed from the workflow file, add `environmentRemovalStrategy: destroy` to your `settings` section. For example:

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

environments:
  vpc:
    name: "VPC and Network"
    templateName: "VPC"
```

| Value | Behavior |
| - | - |
| `destroy` | Automatically destroy removed environments after deploying all environments |
| `detach` | Detach removed environments without destroying them (default) |

> [!WARNING]
>
> **Template Naming**
>
> While not enforced, use unique template names. Otherwise, the Workflow will randomly choose one of the templates without considering permission restrictions.

## Creating a Workflow in the UI

1. Create a [new template](https://docs.envzero.com/guides/admin-guide/templates.md) and select **env zero Workflow** as the Template Type:

![Template creation screen with env zero Workflow selected as the Template Type](https://mintcdn.com/envzero-b61043c8/noVHY1C-wdNQ4iZn/images/guides/admin-guide/workflows/7e4b205-screen_shot_2022-06-08_at_16.png?fit=max\&auto=format\&n=noVHY1C-wdNQ4iZn\&q=85\&s=031d94c14169550423c5a8488d1a42ad)

In the VCS step, fill in your VCS details and the directory that contains your **env0.workflow\.yaml** (or **env0.workflow\.yml**) file:

![VCS step in workflow template setup showing repository and workflow file directory fields](https://mintcdn.com/envzero-b61043c8/noVHY1C-wdNQ4iZn/images/guides/admin-guide/workflows/bec911f-screen_shot_2022-06-08_at_16.png?fit=max\&auto=format\&n=noVHY1C-wdNQ4iZn\&q=85\&s=6779901470b6abd60d4ddbd07963c412)

2. Create an [Environment](https://docs.envzero.com/guides/admin-guide/environments/setting-up-a-new-environment.md) based on the Workflow template.
   You can choose any of the workflow environments from the dropdown menu in the top right corner.

![Workflow environment creation screen with sub-environment selector dropdown](https://mintcdn.com/envzero-b61043c8/noVHY1C-wdNQ4iZn/images/guides/admin-guide/workflows/9d4cf3b-screen_shot_2022-11-30_at_19.png?fit=max\&auto=format\&n=noVHY1C-wdNQ4iZn\&q=85\&s=66e4e17f97aa5adb935589a49e42ed62)

After choosing one of the workflow sub-environments, you can modify its variables, workspace, revision and auto-approval settings.

> [!NOTE]
>
> Remote Backend
>
> The Remote Backend option applies to Terraform and OpenTofu sub-environments when env zero creates them. To enable it on an existing sub-environment, see [Enable Remote Backend on a workflow sub-environment](https://docs.envzero.com/guides/admin-guide/remote-backend.md#enable-remote-backend-on-a-workflow-sub-environment). For further documentation about remote backend, [follow this guide](https://docs.envzero.com/guides/admin-guide/remote-backend.md).

> [!NOTE]
>
> Overrides Note
>
> The values you set here for workspace and revision will override the ones you've defined in the workflow file for the corresponding environment.
>
> If you would like to set the whole workflow to the same workspace name value, you can do so by setting the workflow workspace name, and leaving the sub environments blank.
>
> Note that since Terragrunt uses a working directory instead of workspace name, the workspace name override won't apply to Terragrunt template type.
>
> When marking the workflow as remote backend, you must provide unique names for each of the sub environments workspaces.

![Sub-environment configuration showing workspace, revision, and auto-approval override options](https://mintcdn.com/envzero-b61043c8/noVHY1C-wdNQ4iZn/images/guides/admin-guide/workflows/953934f-screen_shot_2022-12-21_at_11.png?fit=max\&auto=format\&n=noVHY1C-wdNQ4iZn\&q=85\&s=f721bf284c6dfd90ceeed003a331e689)

3. Deploy

   ![Deploy button to start the workflow deployment after configuration is complete](https://mintcdn.com/envzero-b61043c8/noVHY1C-wdNQ4iZn/images/guides/admin-guide/workflows/de95a1c-image.png?fit=max\&auto=format\&n=noVHY1C-wdNQ4iZn\&q=85\&s=c69abe44cab5e61f66d5b055360ae659)

## Next steps

* [Redeploy or destroy a single sub-environment](https://docs.envzero.com/guides/admin-guide/workflows/workflow-partial-deployment.md) without running the whole workflow
* [Pass outputs between sub-environments](https://docs.envzero.com/guides/admin-guide/variables/workflow-variables.md) with workflow variables


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