13.4 HCP Terraform Integrations

13.4 HCP Terraform Integrations

Quick Answer: Connect a VCS provider at the organization, wire run triggers and notifications on the workspace, publish modules to the private registry, authenticate providers with Dynamic Provider Credentials (OIDC; optionally Vault-backed), and call the API with the right token type. Configure the CLI with a cloud block, not the older backend "remote".

Objective 8d on Terraform Associate (004) is configuration of those integrations. Official references: VCS providers, Run triggers, Notifications, Private registry, Dynamic provider credentials, API tokens, and backend "remote".

VCS connections

A VCS connection is an organization object (OAuth app, GitHub App, or PAT). Workspaces then pick a repository, branch, and optional subdirectory. HashiCorp uses that connection to list repos, register webhooks, and download a commit for a run.

Supported families you should recognize: GitHub.com (GitHub App on HCP Terraform; OAuth on HCP and Enterprise), GitHub Enterprise, GitLab.com and GitLab EE/CE, Bitbucket Cloud and Bitbucket Data Center, Azure DevOps Services and Azure DevOps Server. Unsupported systems use the API-driven workflow instead.

What the webhook does:

• Commit on the tracked branch → queue a real run (apply still follows auto-apply / permissions).
• Pull or merge request → speculative plan, linked on the PR.
• Duplicate commit SHAs are skipped.

Most providers talk HTTPS + OAuth. Azure DevOps Server and Bitbucket Data Center also need an SSH key to fetch contents. Other providers need SSH only for private submodules. You can scope a VCS connection to selected projects so not every team can see every repo. Connecting GitHub App repositories requires a user token that has completed GitHub OAuth; team and organization tokens cannot finish that personal OAuth flow.

Private / on-prem VCS can be reached with HCP Terraform agents. Terraform Enterprise that talks to a public SaaS VCS must allow inbound webhooks from the internet.

Run triggers and notifications

Run triggers connect a downstream workspace to up to 20 source workspaces. When a source apply succeeds, HCP Terraform queues a run downstream. That is how app-prod reacts after net-prod publishes new subnet IDs. Configuring a trigger requires admin on the downstream workspace and permission to read runs on the source.

Pair triggers with data sharing: allow the source workspace's state (or outputs) to be read, then use terraform_remote_state or HashiCorp's preferred tfe_outputs. Triggers do not auto-apply unless Auto-apply run triggers is enabled — a different switch from ordinary auto-apply.

Notifications were covered as a governance channel in 13.2; as an integration, remember destinations (Slack, Microsoft Teams, email, generic webhook), the 20-destination cap, HMAC verification on generic webhooks, and the two hard exclusions: speculative plans and Local execution send nothing.

Private registry

The HCP private registry mirrors the public Terraform Registry UX inside your organization: searchable modules and providers, version constraints, docs. You can synchronize selected public modules/providers inward so the org has an approved catalog. Private modules are usually published by pointing HCP at a VCS repo and pushing a Git tag. Sentinel can require that non-root modules come from that registry. Community CLI can source a public registry address; it does not give you this org-private catalog or its VCS publish flow.

Dynamic Provider Credentials and Vault

The official current name is Dynamic Provider Credentials. Do not write "OIDC auth" as if it were a different HCP product — OIDC is the protocol underneath.

Per plan and per apply, HCP Terraform:

1. Builds a workload identity token (OIDC) that names the organization, workspace or Stack, and run stage.
2. Presents that token to AWS, Azure, GCP, Vault, Kubernetes, or HCP.
3. Receives short-lived credentials, injects them into the runner, and discards them when the disposable environment is torn down.

You set up a trust relationship once on the cloud, then configure workspace environment variables such as TFC_AWS_PLAN_ROLE_ARN / apply-role equivalents, TFC_VAULT_PLAN_ROLE, and the matching Azure/GCP/HCP/Kubernetes variables. Variable sets can share that config. Self-hosted agents need agent v1.7.0+.

Vault-backed dynamic credentials are the two-hop pattern: HCP Terraform authenticates to Vault with OIDC, then Vault's secrets engine mints AWS/GCP/Azure creds. You still configure Vault dynamic credentials first (TFC_VAULT_*), then the cloud-specific Vault-backed variables. Do not also pass token / address into the Vault provider block once the integration owns authentication.

This replaces long-lived AWS_SECRET_ACCESS_KEY environment variables. Community Terraform has no HCP-issued workload identity; you would have to build an equivalent OIDC federation yourself.

Tokens: CLI and API

terraform login writes a user credential for the CLI. Automation should pick a token type on purpose:

Tokens expire. HashiCorp shows the secret once. Organization tokens cannot perform remote operations, create configuration versions, or override policies. If a pipeline must terraform apply through the API, it needs a user or team token with apply rights — not the org token.

cloud block versus backend "remote"

backend "remote" (Terraform ≥ 0.11.13) was the original "enhanced" backend: it stored state in HCP/TFE and could execute CLI-driven runs. As of Terraform 1.1 (and therefore 1.12), HashiCorp recommends the cloud integration instead. cloud supports structured run output and the current workspace-tag model.

// Deprecated shape — still parses; do not write new 1.12 configs this way
terraform {
  backend "remote" {
    organization = "my-org"
    workspaces { prefix = "my-app-" }
  }
}

// Current shape
terraform {
  cloud {
    organization = "my-org"
    workspaces {
      tags = { app = "mine" }
    }
  }
}

Migration is a search-and-replace plus terraform init. name stays name. prefix becomes tags (you then select the full HCP workspace name). hostname still defaults to app.terraform.io. You still must not place a token in the file. You still cannot combine cloud with any backend block.

terraform_remote_state that reads another HCP workspace still uses backend = "remote" in the data source config — that is a reader, not the workspace's own backend declaration. For new sharing inside HCP, prefer tfe_outputs.

Scenario: the pipeline token that does nothing

A platform team creates an organization token, exports it as TFE_TOKEN in GitHub Actions, and calls the Runs API. Create-workspace succeeds; create-run returns an error. The 8d answer is the token type: switch to a team token on a team that has apply on that workspace, or use a dedicated automation user. While they are there, they replace backend "remote" { workspaces { prefix = "pay-" } } with a cloud block and tags, connect GitHub so merges (not the org token) apply pay-prod, and move AWS keys to Dynamic Provider Credentials so the workflow file holds no long-lived cloud secret.

004 traps for objective 8d

• VCS is an org-level connection; the workspace only selects repo/branch.
• Run triggers fire on successful apply, cap 20, separate auto-apply switch.
• Official name: Dynamic Provider Credentials (OIDC). Vault-backed is the Vault hop, not a different exam product.
• Org token ≠ run token.
• cloud replaces backend "remote" for the root module; prefix is not a cloud argument.
• Notifications skip speculative plans and Local mode.