Skip to main content
How the repository is set up covers the cloud block, workspace variables and execution mode. This page covers what to add when you run several brands, or when you want a plan on every pull request.

​
Projects and workspaces

HCP Terraform has three levels: organization, project and workspace.
  • One workspace per tenant. A workspace holds one state file.
  • One project per brand, agency or business unit.
Three brands across dev, QA and production is nine workspaces:
Name the project in the cloud block, alongside the workspace:
A variable set owned by the project applies to every workspace in it, so a value shared across a brand’s tenants is entered once.

​
Access

A project holds a brand’s dev, QA and production workspaces, so granting a team the project gives them production as well.
Anyone who can queue a plan in a workspace can run their own code with the secret key stored in it. Treat access to a production workspace as access to the production tenant.
  • Grant the project to the people who work on that brand.
  • Grant the production workspace separately, to a smaller group.
See team permissions.

​
Plan every pull request

Connect HCP Terraform to your repository and it plans each pull request, then applies on merge.
Applies then come from a merge. A workspace connected to version control refuses a terraform apply from the command line.
  1. In Settings > Version Control > Providers, add GitHub and install the HCP Terraform GitHub App on your repository.
  2. Create each workspace with the Version control workflow, pointed at that repository.
  3. Set the VCS branch and the Terraform working directory, such as envs/dev.
  4. Turn Auto-apply off, so each run waits for approval.
A pull request then gets a plan for each affected workspace, linked from the pull request itself.

​
Working directory and run triggers

The working directory keeps each workspace to its own environment folder. By default it also limits which changes start a run.
A workspace only runs when files in its working directory change. A shared module sits outside every environment folder, so a change to it starts no runs.
Set Automatic run triggering to Always trigger runs, or add trigger patterns covering both folders:
Start one run by hand after creating a workspace. Automatic triggering does not always fire until a workspace has run once.

​
Plan from your machine

A workspace connected to version control still accepts a plan from the command line:
The plan runs in HCP Terraform using that workspace’s variables and state, and reports back in your terminal. It cannot be applied.
If terraform init reports Required token could not be found, unset TF_CLI_CONFIG_FILE and run it again. Terraform reads credentials from that file instead of the one terraform login writes.

​
Example

multi-brand-hcp is a working repository for several brands on HCP Terraform, with a project and workspace declared per environment.