» Workspace Settings

Terraform Enterprise (TFE) workspaces can be reconfigured after creation.

Each workspace's page has two tabs of settings:

  • "Settings," for general configuration.
  • "Version Control," for managing the workspace's VCS integration.

Changing settings requires admin privileges on the affected workspace.

Screenshot: a workspace page's tabs

» General Settings

The following settings are available in the "Settings" tab.

» ID

The permanent unique ID of the workspace, which cannot be changed. Workspace IDs are sometimes necessary when working with TFE's API.

Click the icon beside the ID to copy it to the clipboard.

» Name

The display name of the workspace.

After changing this setting you must click the "Save settings" button below the "Terraform Working Directory" field.

» Auto Apply and Manual Apply

Whether or not TFE should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it.

After changing this setting you must click the "Save settings" button below the "Terraform Working Directory" field.

» Terraform Version

Which version of Terraform to use for all operations in the workspace. You can choose "latest" to automatically update to new versions, or you can lock a workspace to any specific version.

By default, new workspaces are locked to the current version of Terraform at the time of their creation. (You can specify a Terraform version when creating a workspace via the API.)

After changing this setting you must click the "Save settings" button below the "Terraform Working Directory" field.

» Terraform Working Directory

The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. This is useful when working with VCS repos that contain multiple Terraform configurations. Defaults to the root of the configuration directory.

After changing this setting you must click the "Save settings" button below it.

» SSH Key

If a workspace's configuration uses Git-based module sources to reference Terraform modules in private Git repositories, Terraform needs an SSH key to clone those repositories.

This feature is documented in more detail in Using SSH Keys for Cloning Modules.

After changing this setting, you must click the "Update SSH key" button below it.

» Workspace Lock

If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents users with write access from manually queueing runs, prevents automatic runs due to changes to the backing VCS repo, and prevents the creation of runs via the API. To enable runs again, a user must unlock the workspace.

Users with write access can lock and unlock a workspace, but can't unlock a workspace which was locked by another user. Users with admin privileges can force unlock a workspace even if another user has locked it.

Locks are managed with a single "Lock/Unlock/Force unlock <WORKSPACE NAME>" button. TFE asks for confirmation when unlocking.

» Workspace Delete

This section includes two buttons:

  • "Queue destroy Plan"
  • "Delete from Terraform Enterprise"

In almost all cases, you should perform both actions in that order when destroying a workspace.

Queueing a destroy plan destroys the infrastructure managed by a workspace. If you don't do this, the infrastructure resources will continue to exist but will become unmanaged; you'll need to go into your infrastructure providers to delete the resources manually.

Before queueing a destroy plan, you must set a CONFIRM_DESTROY environment variable in the workspace with a value of 1.

» Version Control Settings

The following settings are available in the "Version Control" tab.

» VCS Connection and Repository

You can use the "Select a VCS connection" buttons and "Repository" field to change which VCS repository the workspace gets configurations from. See Creating Workspaces for more details about selecting a VCS repository, and see Connecting VCS Providers to Terraform Enterprise for more details about configuring VCS integrations.

» VCS Branch

Which branch of the repository to use. If left blank, TFE will use the repository's default branch.

» Include submodules on clone

Whether to recursively clone all of the repository's Git submodules when fetching a configuration.