Skip to main content

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.

This guide is for teams moving existing Terraform Cloud or Terraform Enterprise workspaces to env zero. If you’re new to env zero and not migrating from TFC, start with the Quick Start instead.
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 avoids 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 workspace lock/release permissions
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).

​
Before you start

Review these before launching the wizard to avoid surprises mid-migration. Self-hosted VCS (GitHub Enterprise, GitLab self-managed, Bitbucket Data Center) If your workspaces reference repositories on a self-hosted git server, env zero requires a self-hosted agent to reach it. One agent is needed per VCS instance — if you have two Bitbucket Data Center instances, you need two agents. Set these up before migrating workspaces that use self-hosted VCS. Private Terraform modules sourced via git Workspaces that pull modules using ssh:// URLs need an SSH key attached to the environment in env zero. Workspaces using https:// module URLs need a git token configured via a custom flow. Deployments will fail after migration if these credentials are not in place before the first run. .tfvars files for variable configuration If your workspaces use a .tfvars file to supply variable values rather than TFC workspace variables, set the ENV0_TERRAFORM_CONFIG_FILE_PATH environment variable on the migrated environment to point env zero at the correct file. See Custom Terraform Variables File for details.

​
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 five steps:
  1. Connect - enter your TFC organization name and API token
  2. Select Scope - choose which workspaces to migrate
  3. Resolve - provide missing secrets and configure VCS connections
  4. Review - review your selection and create environments in env zero
  5. 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

​
Next steps