To set up a Workflow, follow this simple guide:

env0 relies on a file named env0.workflow.yml to describe the dependencies and configuration of the sub environments in your workflow. Each environment definition in the file should contain:

1. name: Will be displayed in the Workflow graph
2. templateName(optional, conflicts with vcs): A name of a pre-defined template to deploy

   🚧

   Template Naming

   While we don't enforce it, the best practice is to use unique template names.
   Otherwise, the Workflow will randomly choose one of the templates, without considering any permission restrictions.

3. vcs(optional, conflict with templateName): Information to integrate with the VCS and all the information used to create a template
4. needs (optional): An array of sub environments which all must be successfully deployed before this sub environment can start deploying
5. revision: (optional) A revision for this specific environment's Template to deploy
6. workspace (optional): A name for the terraform workspace for a new environment
   Note: The Workspace attribute can not be set for an existing environment.

   📘

   Workspace for other IaCs

   For Helm Templates - The workspace configuration sets the release-name.
   For Pulumi and CloudFormation templates - The workspace configuration sets the stack-name.

7. disabled (optional): Setting this to true will leave this particular environment out of this workflow. Combined with the ability to set environment variables, this is handy for allowing partial workflow deployments
8. requiresApproval (optional): Setting this to true will force this particular environment to require approval in the Workflow, meaning that the Workflow will not proceed with the environments until the deployment is approved

🚧

Prioritization of Environment Approval

It is possible to define an environment in a workflow in multiple ways. Follow this order for prioritizing approval value:

1. Using the ENV0_REQUIRES_APPROVAL environment variable to force approval
2. Approval policy - If an approval policy is defined it will always be evaluated for the environment
3. Value from the UI - Determines whether a value is defined in the UI or from an API request
4. Value defined from the workflow requiresApproval field

Example configuration

environments:
  vpc:
    name: 'VPC and Network'
    templateName: 'VPC'
  db:
    name: DB
    templateName: 'DB'
    requiresApproval: true 
    needs:
      - vpc
  eks:
    name: EKS
    templateName: 'EKS'
    needs:
      - vpc
  service1:
    name: 'Billing Service'
    vcs:
      type: 'terraform'
      terraformVersion: '1.5.7'
      repository: 'https://github.com/env0/templates'
      path: 'aws/hello-world'
      githubInstallationId: 123456789
      # bitbucketClientKey for bitbucket
      # gitlabProjectId for gitlab
    disabled: ${DISABLE_SERVICE_1}   # omit service1 deployment,
                                     # if the interpolated env var DISABLE_SERVICE_1 is true
    needs:
      - db
      - eks
  service2:
    name: 'Configuration Service'
    templateName: 'Configuration Service' 
    revision: feature-branch
    disabled: ${DISABLE_SERVICE_2}
    needs:
      - db
      - eks
  service3:
    name: 'Notification Service'
    templateName: 'Notification Service'
    workspace: env0-workspace
    disabled: ${DISABLE_SERVICE_3}
    needs:
      - db
      - eks

❗️

Removing Environment

Please note that by default, removing an environment from the workflow file and redeploying it is not supported, as your environment will be left detached from the workflow.

If you would like env0 to destroy the removed environments, you need to add a Settings section to yourenv0.workflow.yml

Settings:

environments:
  vpc:
    name: 'VPC and Network'
    templateName: 'VPC'
settings:
	environmentRemovalStrategy: destroy | detach

By setting environmentRemovalStrategy to destroy env0 will automatically destroy the removed environments after deploying all environments

Creating a Workflow in the UI

1. Create a new template and select env0 Workflow as the Template Type:

In the VCS step, fill in your VCS details and the directory that contains your env0.workflow.yml file:

2. Create an Environment based on the Workflow template.
   You can choose any of the workflow environments from the dropdown menu in the top right corner.

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

🚧

Remote Backend

The Remote Backend option will be applied to Terraform templates only. For further documentation about remote backend, follow this guide.

🚧

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.

3. Deploy