> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Terraform in HCP Terraform

> Group workspaces by brand, and plan every pull request.

[How the repository is set up](/knowledge-base/terraform/repository-setup#where-state-is-stored) 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](https://developer.hashicorp.com/terraform/cloud-docs/projects/manage) 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:

```text theme={null}
brand-a (project)     brand-b (project)     brand-c (project)
  brand-a-dev           brand-b-dev           brand-c-dev
  brand-a-qa            brand-b-qa            brand-c-qa
  brand-a-prod          brand-b-prod          brand-c-prod
```

Name the project in the `cloud` block, alongside the workspace:

```hcl theme={null}
# brands/brand-a/dev/main.tf
terraform {
  # ...
  cloud {
    organization = "your-org"
    workspaces {
      name    = "brand-a-dev"
      project = "brand-a"
    }
  }
}
```

A [variable set](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables/managing-variables) 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.

<Warning>
  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.
</Warning>

* Grant the project to the people who work on that brand.
* Grant the production workspace separately, to a smaller group.

See [team permissions](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions/workspace).

## Plan every pull request

Connect HCP Terraform to your repository and it plans each pull request, then applies on merge.

<Warning>
  Applies then come from a merge. A workspace connected to version control refuses a `terraform apply` from the command line.
</Warning>

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](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#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.

<Warning>
  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.
</Warning>

Set **Automatic run triggering** to **Always trigger runs**, or add trigger patterns covering both folders:

```text theme={null}
envs/dev/**
modules/**
```

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:

```bash theme={null}
cd envs/dev
terraform login
terraform plan
```

The plan runs in HCP Terraform using that workspace's variables and state, and reports back in your terminal. It cannot be applied.

<Tip>
  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.
</Tip>

## Example

[`multi-brand-hcp`](https://github.com/authsignal/terraform-examples/tree/main/multi-brand-hcp) is a working repository for several brands on HCP Terraform, with a project and workspace declared per environment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.