» Workspace Settings

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

Workspace settings are separated into several pages, which are listed in the drop-down "Settings" menu in each workspace's header. The following groups of settings are available:

  • "General", for basic configuration.
  • "Locking", for temporarily preventing new plans and applies.
  • "Notifications", for configuring run notifications.
  • "SSH Key", for configurations that use Git-based module sources.
  • "Team Access," for managing workspace permissions.
  • "Version Control", for managing the workspace's VCS integration.
  • "Destruction and Deletion", for removing a workspace and the infrastructure it manages.

Changing settings requires admin privileges on the affected workspace.

Screenshot: a workspace page's "Settings" menu

» General

The "General Settings" page configures a workspace's name, plus some details about how Terraform runs behave.

After changing any of these settings, you must click the "Save settings" button at the bottom of the page.

» ID

Every workspace has a unique ID that 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.

» 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.

Auto-apply has a few exceptions:

  • Destroy plans must always be manually applied.
  • Plans queued by users with plan permissions must be approved by a user with write or admin permissions.

» Terraform Version

Which version of Terraform to use for all operations in the workspace. The default value is whichever release was current when the workspace was created.

You can choose "latest" to automatically update a workspace to new versions, or you can choose a specific version.

» 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.

» Locking

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.

Locking a workspace also restricts state uploads. In order to upload state, the workspace must be locked by the user who is uploading state.

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.

» Notifications

The "Notifications" page allows TFE to send webhooks to external services whenever specific run events occur in a workspace.

See Run Notifications for detailed information about configuring notifications.

» 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. The "SSH Key" page lets you choose which key it should use.

See Using SSH Keys for Cloning Modules for detailed information about this page.

» Team Access

The "Team Access" page configures which teams can perform which actions on a workspace.

See Managing Access to Workspaces for detailed information.

» Version Control

The "Version Control" page configures the VCS repository (if any) that contains the workspace's Terraform configuration.

After changing any of these settings, you must click the "Update VCS settings" button at the bottom of the page.

» 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 also:

» 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.

» Destruction and Deletion

This page 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 go to the workspace's variables page and set an environment variable with a name of CONFIRM_DESTROY and a value of 1.