» Creating Workspaces

Hands-on: Try the Get Started - Terraform Cloud collection on HashiCorp Learn.

Workspaces organize infrastructure into meaningful groups. Create new workspaces whenever you need to manage a new collection of infrastructure resources.

Each new workspace needs a unique name, and needs to know where its Terraform configuration will come from. Most commonly, the configuration comes from a connected version control repository. If you choose not to connect a repository, you'll need to upload configuration versions for the workspace using Terraform CLI or the API.

For more information about how configuration versions and connected repositories work, see Terraform Configurations in Terraform Cloud Workspaces.

» Required Permissions

New workspaces can be created by teams with permission to manage workspaces. (More about permissions.)

» Configuring a New Workspace

To create a new workspace:

  1. Navigate to the workspace list and click the "+ New Workspace" button (near the top of the page).

  2. On the first screen, choose your VCS provider (or choose "No VCS connection").

  3. On the second screen, choose a repository from the filterable list. This screen is skipped if you chose "No VCS connection".

    Some VCS providers limit the list's size. If a repository isn't listed, you can still choose it by name; scroll to the bottom of the list and enter its ID in the text field.

  4. On the third screen, enter a name for the workspace. This defaults to the repository name, if applicable. The name must be unique within the organization, and can include letters, numbers, dashes (-), and underscores (_). See also our advice for useful workspace names.

  5. Optionally, click the "Advanced options" link on the third screen to configure some additional version control settings. (These settings not shown if you chose "No VCS connection".) For information about these settings, see:

  6. Confirm creation with the "Create workspace" button.

» After Creating a Workspace

When you create a new workspace, a few things happen:

  • Terraform Cloud doesn't immediately queue a plan for the workspace. Instead, it presents a dialog with shortcut links to either queue a plan or edit variables.

    If you don't need to edit variables, confirm that the workspace is ready to run by manually queuing a plan.

  • If you connected a VCS repository to the workspace, Terraform Cloud automatically registers a webhook with your VCS provider. The next time new commits appear in the selected branch of that repo or a PR is opened to that branch, Terraform Cloud will automatically queue a Terraform plan for the workspace. For more information, see VCS Connections: Webhooks.

A workspace with no runs will not accept new runs via VCS webhook; at least one run must be manually queued to confirm that the workspace is ready for further runs.

Most of the time, you'll want to do one or more of the following after creating a workspace: