CI/CD with HCP Terraform

New to compliance.tf CI/CD? See the CI/CD overview for prerequisites and authentication concepts.

How HCP Terraform Authentication Differs

HCP Terraform (formerly Terraform Cloud) 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.

You must set the token as a workspace environment variable inside HCP Terraform.

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 of repeating this on every workspace.

No Pipeline File Needed

HCP Terraform manages the init/plan/apply lifecycle. Once the environment variable is set, terraform init authenticates against the compliance.tf registry automatically. No additional pipeline configuration is required.

Variable Sets for Multiple Workspaces

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

Creating a variable set

1. Go to your organization Settings > Variable Sets
2. Click Create variable set
3. Name it something descriptive (e.g., "compliance.tf Registry Credentials")
4. Under Variable set scope, choose how broadly to apply it:
   • Apply to all workspaces in the organization — simplest option, 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 — fine-grained control 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

Multiple framework endpoints

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

The same token value works for all endpoints — 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 if needed (for example, to use a different token for a staging workspace during token rotation).

VCS-Driven Workflows

HCP Terraform's VCS integration works with compliance.tf modules without any extra configuration. The flow is:

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 webhook configuration, no custom run tasks, and no wrapper scripts. As long as the token is set as a workspace or variable-set environment variable, VCS-driven runs authenticate automatically.

Run Triggers

Run triggers work normally with compliance.tf modules. When workspace A completes an apply and triggers a run in workspace B, workspace B uses its own environment variables during terraform init.

Each workspace (or the variable set applied to it) provides the compliance.tf token independently. No additional configuration is needed on the run trigger itself.

Agent Pools

Organizations that require private network access — for example, if compliance.tf traffic must route through a corporate proxy or VPN — can use HCP Terraform agent pools instead of HCP Terraform's shared workers.

Agents are lightweight processes that you run in your own infrastructure. They connect to HCP Terraform, pick up queued runs, and execute Terraform locally within your network.

To configure compliance.tf authentication on agents:

1. Set TF_TOKEN_soc2_compliance_tf as an environment variable in the agent's runtime environment (e.g., in the container definition, systemd unit, or shell profile).
2. Assign the agent pool to the relevant workspaces in HCP Terraform.
3. Runs in those workspaces execute on your agents, which use the locally configured token.

---

Next steps

• Audit evidence — turn the runs your workspaces produce into evidence an auditor accepts.
• CI/CD overview — authentication concepts and setup for the other pipelines you run.

Reference: HCP Terraform workspace variables and HCP Terraform agents