HCP Terraform

For teams that run Terraform in HCP Terraform (formerly Terraform Cloud) workspaces. When you finish, every remote or agent run's terraform init downloads compliance.tf modules with a sensitive environment variable, with no pipeline file to change. Authentication concepts shared by every platform are on CI/CD integration.

Before you start

• An organization-owned registry token for this pipeline, created on the organization's tokens screen: see Create a token. CI/CD integration explains why a personal or terraform login token will not do.
• Permission to edit workspace variables, or organization variable sets, in HCP Terraform.

What differs on this platform

HCP Terraform workspaces default to remote execution: terraform init runs on HCP Terraform's workers (or your agents), not in your local environment, so local credentials files (~/.terraformrc) and local environment variables have no effect. This page covers remote and agent execution. Workspaces set to local execution run Terraform on your machine and ignore workspace variables; use the local CLI credential setup from Get started instead.

The token must be a workspace environment variable inside HCP Terraform.

Step 1: Store the token

For a single workspace:

1. Open your workspace in HCP Terraform
2. Go to Variables > Environment Variables
3. Click Add variable
4. Key: TF_TOKEN_soc2_compliance_tf
5. Value: paste your token
6. Check Sensitive

Managing more than a handful of workspaces? Define the token once in a variable set instead.

For many workspaces: a variable set

A variable set holds the token once, and HCP Terraform injects it into every workspace in scope, including workspaces that do not exist yet.

1. Go to your organization Settings > Variable Sets
2. Click Create variable set
3. Name it something descriptive (for example, "compliance.tf Registry Credentials")
4. Under Variable set scope, choose how broadly to apply it:
   • Apply to all workspaces in the organization: every workspace gets the token automatically, including workspaces created in the future.
   • Apply to specific projects: scopes the token to one or more HCP Terraform projects. Useful when only certain teams use compliance.tf modules.
   • Apply to specific workspaces: for cases where only a few workspaces need registry access.
5. Add an Environment variable:
   • Key: TF_TOKEN_soc2_compliance_tf
   • Value: your compliance.tf token
   • Check Sensitive
6. Save the variable set

If your organization uses HCP Terraform projects to group workspaces by team or environment, project-scoped variable sets keep the token available to every workspace in the project without exposing it organization-wide.

Several framework hosts

If you use more than one compliance.tf framework host (for example SOC 2 and HIPAA), add a TF_TOKEN_* variable for each hostname in the same variable set:

The same token value works for all of them; only the variable name changes.

Precedence

If a workspace has its own environment variable with the same key as a variable set, the workspace-level variable takes precedence. This lets you override the organization-wide token for specific workspaces, for example to use a different token for a staging workspace during token rotation.

Step 2: Configure the pipeline

There is no pipeline file to change. HCP Terraform manages the init, plan and apply lifecycle, and once the environment variable is set, terraform init authenticates against the compliance.tf registry on every run type below.

VCS-driven runs

1. You push a commit to your connected repository.
2. HCP Terraform detects the change and queues a run.
3. HCP Terraform runs terraform init on its workers, which reads the TF_TOKEN_soc2_compliance_tf environment variable and authenticates against the compliance.tf registry.
4. HCP Terraform downloads the compliance.tf modules and runs terraform plan.
5. If the plan succeeds and auto-apply is enabled (or you confirm manually), HCP Terraform runs terraform apply.

No webhooks, custom run tasks, or wrapper scripts are needed. Speculative plans on pull requests use the same workspace environment variables. The token is available to them too.

Run triggers

Run triggers work normally. When workspace A finishes an apply and triggers a run in workspace B, workspace B uses its own environment variables or its variable set during terraform init. The run trigger itself needs no configuration.

Agent pools

If your organization needs private network access, for example when compliance.tf traffic must go through a corporate proxy or VPN, you can use HCP Terraform agent pools instead of the shared workers. Agents run in your own infrastructure. They pick up queued runs and execute Terraform within your network.

Workspace-level environment variables and variable sets are injected into the agent's run environment automatically, so setting the token through a variable set is usually enough. Configure TF_TOKEN_soc2_compliance_tf on the agent itself (in the container definition, systemd unit or shell profile) only when the agent must authenticate outside HCP Terraform-managed runs, such as in custom pre-run scripts.

Check the result

Queue a plan in a workspace that uses compliance.tf modules. In the run's plan log, terraform init lists each compliance.tf module as downloaded from its host, for example Downloading soc2.compliance.tf/terraform-aws-modules/s3-bucket/aws 5.0.0 for s3_bucket....

Troubleshooting

• Init fails although the variable exists. It was added as a Terraform variable rather than an environment variable; see What differs on this platform.
• A local run fails while remote runs work. The workspace uses local execution, which ignores workspace variables; set up local credentials from Get started.
• One workspace uses a different token than the rest. A workspace variable with the same key overrides the variable set; see Precedence.
• 401 Unauthorized, 403 Forbidden or a registry error at init. See Troubleshooting on CI/CD integration.

Next steps

• Audit evidence - turn the runs your workspaces produce into evidence an auditor accepts
• Turn controls on and off - relax or add controls per module in the source line
• CI/CD integration - authentication concepts and setup for the other pipelines you run

Reference: HCP Terraform workspace variables and HCP Terraform agents