» Creating Workspaces

Create new Terraform Cloud workspaces with the "+ New Workspace" button, which appears on the list of workspaces. If you're not already viewing the workspace list, you can get there with the "Workspaces" button in the top navigation bar.

» Configuring a New Workspace

screenshot: form fields on the new workspace page

You must fill out several fields to configure your new workspace:

  • Workspace name (required) — A name for the workspace, which must be unique in the organization. Names can include letters, numbers, _, and -. See more advice about workspace names here.
  • Source (required; list of buttons) — Which connected VCS provider the workspace should pull configurations from. If you've configured multiple VCS providers, there is a button for each of them.

If you select "None," the workspace cannot pull configurations automatically, but you can upload configurations with the remote backend or the run API.

  • Repository — The VCS repository that contains the Terraform configuration for this workspace. This field is hidden when creating a workspace without a VCS source.

Repository identifiers are determined by your VCS provider, and use a format like <ORGANIZATION>/<REPO NAME> or <PROJECT KEY>/<REPO NAME>.

This field supports autocompletion of your most recently used repositories. If you need to specify a repository that isn't included in the autocomplete list, you can enter the full name manually.

If necessary, you can change a workspace's VCS repository after creating it.

Screenshot: VCS repo autocompletion

VCS-backed workspaces support several optional fields, which you can reveal by clicking the "More options" link. These fields are hidden when creating a workspace without a VCS source.

Screenshot: Optional fields for new VCS-backed workspaces

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

  • Automatic run triggering — If you specify a working directory, Terraform Cloud will by default only queue a plan for changes to the repository inside that working directory. You can override this behaviour with these settings. See Automatic Run Triggering settings for more details.

Screenshot: Controlling run triggering for workspaces with working directory

  • VCS branch — Which branch of the repository to use. If left blank, Terraform Cloud will use the repository's default branch.
  • Include submodules on clone (checkbox) — Whether to recursively clone all of the repository's Git submodules when fetching a configuration.

» 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, manually queuing a plan confirms that the workspace is ready to run.
  • If you selected a VCS provider and repository, Terraform Cloud automatically registers a webhook. 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. More at VCS Connection 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: