Skip to main content
The env zero migration wizard enables teams to move Terraform Cloud (TFC) and Terraform Enterprise (TFE) workspaces into env zero quickly and safely, without rebuilding environments or manually transferring configuration. The wizard automatically discovers your existing workspaces and recreates them in env zero, including:
  • Workspace configuration
  • Variables and variable sets
  • Terraform state
  • Version control settings
The migration process runs directly from the env zero UI and follows a controlled migration flow. Your original Terraform Cloud workspaces remain unchanged during the process, allowing teams to validate environments in env zero before completing the final Go Live step. This approach allows organizations to migrate infrastructure gradually, verify configurations safely, and transition execution to env zero without interrupting existing deployments.

​
What this migration covers

  • Automatic discovery of TFC/TFE workspaces, variables, and variable sets
  • 1:1 replication of project structure, workspace settings, and variables
  • Terraform Cloud state migration to the env zero remote backend
  • Controlled cutover with TFC workspace locking and env zero environment unlocking
  • Gradual migration: migrate a few workspaces at a time and return later to continue with the rest

​
What is not migrated automatically

The wizard focuses on workspaces, variables, state, and VCS configuration. The following TFC/TFE entities are not migrated and need to be recreated manually in env zero after migration:
  • Private module registry - re-publish modules in the env zero module registry
  • Policies (Sentinel / OPA) - recreate as env zero custom flows or policy rules
  • Run triggers and workspace dependencies - configure workflow triggers in env zero
  • Team permissions and RBAC - configure SSO/SAML integration in env zero to manage identity and access. This is more robust than migrating individual TFC team permissions and ensures your identity provider remains the single source of truth for access control
  • Notification configurations - configure notifications in env zero
  • SSH keys - add SSH keys to env zero as needed

​
Prerequisites

env zero access:
  • Admin role or Edit Organization Settings permission
Terraform Cloud / Terraform Enterprise access:
  • A TFC/TFE user or team API token with read permissions and permissions to lock/unlock workspaces
To create a TFC API token: log in to Terraform Cloud and go to User Settings > Tokens to generate a user token, or go to Organization Settings > Teams, select your team, and generate a team token. The token needs read access to workspaces, variables, variable sets, and state, plus permissions to lock and unlock workspaces (used during go-live).

​
How concepts map between TFC and env zero

TFC/TFE conceptenv zero concept
ProjectProject
WorkspaceEnvironment
Workspace variablesEnvironment variables
Variable setsConfiguration sets
VCS settingsTemplate VCS settings
Remote backend stateenv zero remote backend

​
Migration flow

The wizard guides you through four steps:
  1. Connect and Scan - connect your TFC organization and discover workspaces
  2. Resolve Issues - provide missing secrets and configure VCS connections
  3. Review and Migrate - review your selection and create environments in env zero
  4. Go Live - lock TFC workspaces and activate env zero environments
You do not need to migrate everything at once. Select a group of workspaces, migrate and go live with them, then return to the wizard to select the next group. Your session is preserved between visits.
Your TFC workspaces are never modified or deleted during the migration. They remain fully operational until you explicitly go live.

​
Getting started

Navigate to Organization Settings > Migration to launch the wizard, then click Start Migration.
If you have an active migration session, a TFC Migration widget appears on your homepage with a Resume Migration button.

​
Pages in this guide