» 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

Terraform Cloud presents a dialog with shortcut links to either queue a plan or edit variables. If you don't need to edit variables, manually queue a run to prepare your workspace.

You may also want to:

» VCS Connection

If you connected a VCS repository to the workspace, Terraform Cloud automatically registers a webhook with your VCS provider. A workspace with no runs will not accept new runs from a VCS webhook, so you must manually queue at least one run.

After you have manually queued a run, Terraform Cloud will automatically queue a plan for the workspace when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch. Learn more about VCS webhooks.