CI/CD with Terraform Cloud

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

How TFC Authentication Differs

Terraform Cloud runs terraform init on its own workers, not in your local environment. This means local credentials files (~/.terraformrc) and local environment variables have no effect during remote execution.

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

Store the Token

Per workspace:

1. Open your workspace in Terraform Cloud
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

Organization-wide (recommended):

1. Go to your organization Settings > Variable Sets
2. Create a new variable set (e.g., "compliance.tf credentials")
3. Add an environment variable: TF_TOKEN_soc2_compliance_tf with your token, marked as Sensitive
4. Apply the variable set to all workspaces (or selected workspaces)

Variable sets avoid repeating the token configuration in every workspace.

No Pipeline File Needed

Terraform Cloud 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

If you manage more than a handful of workspaces, setting the token individually on each one becomes tedious and error-prone. Variable sets let you define the token once and apply it broadly.

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 TFC 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 (not a Terraform 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

Terraform Cloud'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. TFC detects the change and queues a run.
3. TFC runs terraform init on its workers, which reads the TF_TOKEN_soc2_compliance_tf environment variable and authenticates against the compliance.tf registry.
4. TFC downloads the compliance.tf modules and runs terraform plan.
5. If the plan succeeds and auto-apply is enabled (or you confirm manually), TFC 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.

Remote Execution

Terraform Cloud uses a remote execution model: when you run terraform plan or terraform apply (whether from the UI, API, or CLI), the actual Terraform process runs on TFC's workers — not on your local machine.

This has one important implication for authentication:

• Local execution reads credentials from ~/.terraformrc or ~/.terraform.d/credentials.tfrc.json on your machine.
• Remote execution ignores local credential files entirely. The TFC worker has no access to your local filesystem.

The token must be set as an environment variable in the workspace (or via a variable set). Setting it as a Terraform variable does not work — Terraform variables are passed to your configuration as var.* values, not used for registry authentication.

Agent Pools

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

Agents are lightweight processes that you run in your own infrastructure. They connect to Terraform Cloud, 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 TFC.
3. Runs in those workspaces execute on your agents, which use the locally configured token.

Reference: Terraform Cloud agents documentation

Reference: Terraform Cloud workspace variables