Running ad hoc tasks

Sometimes you may want to execute arbitrary commands on your deployment container - for example, manually altering the state or manipulating a local file. These commands can be run using Custom Flows, but that requires committing the commands to your git repository, which doesn’t always fit the use case. In these cases, it is possible to execute Run a Task on the deployment container.

​

Executing a Run Task

From the environment’s advanced context menu, click on Run a Task.
It will prompt you to enter the commands you desire to execute.
Enter the commands, as you would in a bash script. Separate commands with new lines.
When you are ready to run your task - click the RUN A TASK button below. Your task will be queued and executed on the deployment container, including the local cache env zero saves between deployments. You’ll be able to see your commands execute in the Deployment Logs, like any other deployment.
During the task execution, all the variables that are defined in the environment will be available for you to use. Tasks also support custom flows. You can read more about the available hooks here.

​

Common Tasks

• Migrate state: terraform init -migrate-state -force-copy or echo "yes" | terraform init -migrate-state
• Release state lock: terraform force-unlock -force LOCK_ID [DIR]
• Retrieve output: terraform output [options] [NAME]
• Taint a resource terraform taint [options] <address>
• Move state: terraform state mv [options] SOURCE DESTINATION

​

Tasks and Terraform Init

Tasks do not clone your source code. When the environment has a working directory archive from a previous deployment, env zero restores it and runs your script against it, and that archive does not include Terraform provider binaries (.terraform/providers). For Terraform, OpenTofu, and Terragrunt environments, env zero runs an init step before your task script whenever the restored working directory is missing its provider cache. Your script still runs exactly as you wrote it, and you do not need to add terraform init yourself. The init step does not run when:

• The provider binaries are already in the working directory, for example after an agent version that still archived them.
• The environment uses a tool with no init step, such as Pulumi, Helm, Kubernetes, Ansible, or CloudFormation.
• ENV0_ARCHIVE_TF_PROVIDERS=true is set, because the archive still carries the providers.
• There is no working directory to restore, which is covered in the next section.

If the init step fails, for example because the deployment container cannot reach the provider registry or a mirror, the task fails with the init error and your script does not run. To keep provider binaries in the archive, see Keep Terraform Providers in the Working Directory Archive.

​

Tasks on Environments With No Working Directory

You can run a task on an environment that has never been deployed, and on one whose working directory archive has expired. A task is often how you inspect or repair an environment before it has ever run, so it does not require a deployment first. env zero notes what it found in the deployment log and runs your script either way: against the state files alone when those are still available, or in an empty working directory when they are not. Nothing is initialized in that case, so a task that needs Terraform providers or modules has to run terraform init itself before anything else.

​

Task Comments

You can add a comment, to let your teammates know why the task was run.
Add a comment, by filling in the “Comment” input down below the bash input. The comment will be displayed in the Task page.
Markdown syntax is supported.

​

Next steps

• Custom flows overview - Commit reusable command hooks to your git repository.
• Managing variables - Access and manage the variables available during task execution.
• Environment overview - Review the deployment container and state lifecycle.