Env0 Integration

💡 NOTE: For the latest details and examples, see the Overmind Env0 plugin repository on GitHub: overmindtech/env0-plugin and the Env0 plugin documentation at Env0 Plugins Overview.

The Overmind Env0 plugin lets you connect your Env0 Terraform deployments directly to Overmind. It:

Submits Terraform plans from Env0 to Overmind for blast radius and risk analysis
Tracks change lifecycle, marking when a deployment starts and finishes
Links changes back to Env0, so every change in Overmind has a ticket link to the corresponding Env0 deployment
Posts simulation results to GitHub PRs or GitLab MRs for visibility during code review

How It Works

The Env0 plugin runs as a standard Env0 version: 2 plugin defined in your env0.yaml:

Plugin installation – Env0 clones the public plugin repository and executes it as a Bash-based plugin.
Overmind CLI install – The plugin downloads and installs the latest Overmind CLI and GitHub CLI (for GitHub support) into a writable directory on the PATH. GitLab support uses curl which is typically available on most systems.
Authentication – The api_key input is exported as OVERMIND_API_KEY so the CLI can authenticate.
Action execution – Based on the action input, the plugin runs one of:
- submit-plan: Uses the Env0-provided $ENV0_TF_PLAN_JSON to submit a Terraform plan to Overmind
- start-change: Marks the beginning of a change in Overmind
- end-change: Marks the completion of a change in Overmind
- wait-for-simulation: Retrieves Overmind simulation results as Markdown and (when post_comment=true) posts them to the GitHub PR or GitLab MR
Ticket link – For all actions, the plugin builds a ticket link back to the Env0 deployment using Env0 environment variables (ENV0_PROJECT_ID, ENV0_ENVIRONMENT_ID, ENV0_DEPLOYMENT_LOG_ID, ENV0_ORGANIZATION_ID). This ticket link is attached to the Overmind change so you can always trace back to the original Env0 run.

Requirements

Before configuring the integration, ensure:

Overmind account with an API key that has the following scopes:
- account:read
- changes:write
- config:write
- request:receive
- sources:read
- source:write
Env0 environment variables are available at runtime (Env0 sets these automatically for Terraform runs):
- ENV0_PROJECT_ID
- ENV0_ENVIRONMENT_ID
- ENV0_DEPLOYMENT_LOG_ID
- ENV0_ORGANIZATION_ID
- ENV0_TF_PLAN_JSON – required for the submit-plan action
- ENV0_PR_NUMBER – required when wait-for-simulation posts comments (i.e. running against a PR/MR)
- ENV0_PR_SOURCE_REPOSITORY – required when wait-for-simulation posts comments (used to detect GitHub vs GitLab)
Terraform plan JSON – Env0 must be configured to produce a JSON plan (Env0 normally populates ENV0_TF_PLAN_JSON after a terraformPlan step).
GitHub authentication – When wait-for-simulation posts to GitHub, set GH_TOKEN (see Creating a GH_TOKEN).
GitLab authentication – When wait-for-simulation posts to GitLab, set GITLAB_TOKEN (see Creating a GITLAB_TOKEN).

Store your Overmind API key in Env0 as a secure environment variable (for example OVERMIND_API_KEY) and pass it to the plugin via the api_key input.

Plugin Inputs

The Env0 plugin exposes the following inputs:

Input	Description	Required
`action`	The action to perform. Must be one of: `submit-plan`, `start-change`, `end-change`, `wait-for-simulation`.	Yes
`api_key`	Overmind API key used for authentication. Must have scopes: `account:read`, `changes:write`, `config:write`, `request:receive`, `sources:read`, `source:write`.	Yes
`tags`	Comma-separated `key=value` tags to attach to the change (only used with `submit-plan`).	No
`post_comment`	Whether `wait-for-simulation` should post the Overmind markdown to GitHub PR or GitLab MR. Defaults to `true` when running against a PR/MR, otherwise `false`. When `true`, `comment_provider` must be set.	No
`comment_provider`	Where `wait-for-simulation` should post comments when `post_comment=true`. Must be one of: `github`, `gitlab`.	No
`on_failure`	Behavior when the plugin step errors. `fail` (default) fails the step and blocks the deployment; `pass` allows the deployment to continue even if this step errors.	No
`skip_after_approval`	When `true` (default), `submit-plan` exits early once a deployment has been approved (`ENV0_REVIEWER_NAME` is set), avoiding duplicate analysis from the post-approval re-plan. Set to `false` to submit on every plan.	No

Tags are useful for categorisation, for example:

environment=production
team=platform
service=billing

Basic Setup

Add the plugin to your env0.yaml and reference the public repository:

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Submit Plan to Overmind
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: submit-plan
            api_key: ${OVERMIND_API_KEY}

In this example:

Env0 runs your normal terraformPlan step.
After the plan completes, the plugin:
- Uses ENV0_TF_PLAN_JSON to submit the plan to Overmind.
- Attaches Env0 deployment details as a ticket link.
- Creates or updates a Change in Overmind with blast radius and risk analysis.

You can optionally attach tags to the change:

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Submit Plan to Overmind
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: submit-plan
            api_key: ${OVERMIND_API_KEY}
            tags: environment=production,team=platform

Tracking Change Lifecycle

To get full before/after snapshots and lifecycle tracking in Overmind, add the start-change and end-change actions around your terraformApply step.

Mark Change Started (before `terraformApply`)

Configure a before hook on terraformApply:

version: 2
deploy:
  steps:
    terraformApply:
      before:
        - name: Mark Change Started
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: start-change
            api_key: ${OVERMIND_API_KEY}

This will:

Look up the relevant Change in Overmind (typically created during submit-plan).
Mark it as started, capturing a snapshot of current infrastructure state.

Mark Change Finished (after `terraformApply`)

Configure an after hook on terraformApply:

version: 2
deploy:
  steps:
    terraformApply:
      after:
        - name: Mark Change Finished
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: end-change
            api_key: ${OVERMIND_API_KEY}

This will:

Mark the Change as completed in Overmind.
Capture a post-deployment snapshot to understand exactly what changed.
Keep the Env0 deployment ticket link associated with the Change for easy navigation.

Skipping the Post-Approval Re-Plan

Env0's plan-and-apply workflow runs terraformPlan twice per deployment when manual approval is enabled:

PR plan event — fires when an MR/PR is opened or updated. Reviewers consume the Overmind analysis.
Deploy event — fires after approval. Env0 always re-runs terraform plan between approval and apply, even if the code hasn't changed.

By default the plugin places submit-plan on terraformPlan.after, which means the second plan would trigger a duplicate Overmind analysis that no one reviews. Worse, start-change then waits for that redundant analysis to finish before proceeding to apply.

To avoid this, the plugin checks ENV0_REVIEWER_NAME — an environment variable that env0 only sets once a reviewer has approved the deployment (see the env0 Custom Flows FAQ). When skip_after_approval is true (the default) and ENV0_REVIEWER_NAME is set, submit-plan exits early with a log message.

Why `ENV0_REVIEWER_NAME` and not `ENV0_DEPLOYMENT_TYPE`

ENV0_DEPLOYMENT_TYPE has values like deploy, destroy, prPlan, driftDetection, and task. Filtering on prPlan alone would break two real scenarios:

Customers without "Run plan on Pull Request" enabled — no prPlan event ever fires; they trigger deploy directly and need submit-plan to run.
destroy pipelines — highest-stakes changes; blast-radius analysis is valuable here too.

ENV0_REVIEWER_NAME is the conservative, correct gate: env0 only sets it after a human clicks approve, which means a prior plan was already submitted to Overmind.

Scenario	`ENV0_REVIEWER_NAME`	`submit-plan` behaviour
`prPlan` event (PR opened/updated)	unset	runs (fresh PR plan)
`deploy` after manual approval	set	skipped
`deploy` with auto-approval	unset	runs (only chance to submit)
`deploy` triggered directly (no approval gate)	unset	runs
`destroy` after manual approval	set	skipped (prior plan already submitted)
`destroy` with auto-approval	unset	runs
`driftDetection` / `task`	unset	runs

Opting out

If your workflow requires both submissions (for example, you have auto-deploy environments where the only terraformPlan event happens during the deploy pipeline and there is no prior PR plan), set skip_after_approval: false:

- name: Submit Plan to Overmind
  use: https://github.com/overmindtech/env0-plugin
  inputs:
    action: submit-plan
    api_key: ${OVERMIND_API_KEY}
    skip_after_approval: false

Wait for Simulation

The wait-for-simulation action fetches the latest Overmind simulation summary for the current Env0 deployment and optionally comments on the matching GitHub pull request or GitLab merge request.

By default the plugin posts comments whenever the deployment runs in the context of a PR/MR. Set post_comment: false to skip commenting. When post_comment=true, you must set comment_provider to github or gitlab.

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Post Overmind Simulation
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: wait-for-simulation
            api_key: ${OVERMIND_API_KEY}
            post_comment: false # optional override

To post a comment to a GitHub PR:

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Post Overmind Simulation (GitHub)
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: wait-for-simulation
            api_key: ${OVERMIND_API_KEY}
            post_comment: true
            comment_provider: github

To post a comment to a GitLab MR:

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Post Overmind Simulation (GitLab)
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: wait-for-simulation
            api_key: ${OVERMIND_API_KEY}
            post_comment: true
            comment_provider: gitlab

Fail-safe Mode

By default, if the plugin step fails (e.g. Overmind API error, missing env var, network issue), Env0 treats the step as failed and can block the deployment. To allow the deployment to continue even when this step errors, set on_failure: pass:

- name: Submit Plan to Overmind
  use: https://github.com/overmindtech/env0-plugin
  inputs:
    action: submit-plan
    api_key: ${OVERMIND_API_KEY}
    on_failure: pass # deployment continues even if this step fails

Use on_failure: pass when the Overmind integration is optional and you do not want plugin failures to block deployments.

Complete Example

Here is a complete env0.yaml example that uses all actions:

version: 2
deploy:
  steps:
    terraformPlan:
      after:
        - name: Submit Plan to Overmind
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: submit-plan
            api_key: ${OVERMIND_API_KEY}
            tags: environment=production,team=platform

    terraformApply:
      before:
        - name: Mark Change Started
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: start-change
            api_key: ${OVERMIND_API_KEY}

      after:
        - name: Mark Change Finished
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: end-change
            api_key: ${OVERMIND_API_KEY}

        - name: Post Overmind Simulation
          use: https://github.com/overmindtech/env0-plugin
          inputs:
            action: wait-for-simulation
            api_key: ${OVERMIND_API_KEY}
            post_comment: true
            comment_provider: github

With this configuration:

Every Env0 plan is sent to Overmind for blast radius and risk analysis.
Every Env0 apply is tracked from start to finish in Overmind.
Each Change in Overmind includes a ticket link back to the Env0 deployment for full traceability.
Simulation results are posted as comments on the GitHub PR for easy review.

Creating a `GH_TOKEN`

The wait-for-simulation action calls gh pr comment for GitHub repositories, which requires a GitHub personal access token. To create one:

Sign in to GitHub and open https://github.com/settings/tokens/new (or the fine-grained token wizard).
Choose Classic token, set an expiry that matches your security policy, and select the repo scope (read/write is needed to comment on PRs).
Generate the token and copy it immediately — GitHub will not show it again.
Store the token securely in Env0 (for example as an environment variable or secret) and expose it to the plugin as GH_TOKEN.

Creating a `GITLAB_TOKEN`

The wait-for-simulation action uses the GitLab API to post comments on merge requests for GitLab repositories. To create a GitLab personal access token:

Sign in to GitLab and navigate to your user settings (or group/project settings for project/group tokens).
Go to Access Tokens (or Preferences > Access Tokens for user tokens).
Create a new token with the api scope (read/write is needed to comment on merge requests).
Generate the token and copy it immediately — GitLab will not show it again.
Store the token securely in Env0 (for example as an environment variable or secret) and expose it to the plugin as GITLAB_TOKEN.

note

When post_comment=true, you must set comment_provider to github or gitlab.

Troubleshooting

If the plugin does not behave as expected, check the following:

Env0 plugin logs – Env0 shows plugin execution logs in the deployment details; look for Overmind-related errors.
API key scopes – Ensure the API key used in api_key has all required scopes.
Environment variables – Verify that Env0 is setting ENV0_TF_PLAN_JSON (for submit-plan) and other ENV0_* variables for your deployment. For wait-for-simulation, ensure ENV0_PR_NUMBER and ENV0_PR_SOURCE_REPOSITORY are available when posting comments.
Authentication tokens – When using wait-for-simulation with post_comment=true, ensure GH_TOKEN (for GitHub) or GITLAB_TOKEN (for GitLab) is set in your Env0 environment.
Plugin path – The plugin uses ENV0_PLUGIN_PATH (as described in the Env0 plugin docs) to locate its files; ensure you are not overriding this in your environment.

For more advanced usage patterns or updates to the plugin behaviour, see the GitHub repository: https://github.com/overmindtech/env0-plugin.

How It Works​

Requirements​

Plugin Inputs​

Basic Setup​

Tracking Change Lifecycle​

Mark Change Started (before terraformApply)​

Mark Change Finished (after terraformApply)​

Skipping the Post-Approval Re-Plan​

Why ENV0_REVIEWER_NAME and not ENV0_DEPLOYMENT_TYPE​

Opting out​

Wait for Simulation​

Fail-safe Mode​

Complete Example​

Creating a GH_TOKEN​

Creating a GITLAB_TOKEN​

Troubleshooting​