Reference architecture · v0.4 · November 2026

Pull Request to Production.

A reference architecture for Terraform® delivery on GitHub® Agentic Workflows, with an agent in the pipeline. Turf™ is an autonomous infrastructure-as-code tool for agentic workflows, built on OpenTofu™.

Read the PDF The repo on GitHub

13 pages · PDF · for platform engineers who run Terraform through CI/CD

The pipeline

Terraform in your CI/CD pipeline today.

HashiCorp’s tutorial draws the pipeline most teams run: Terraform plans on every pull request and applies on every merge, through GitHub Actions. Two things go wrong with it.

The plan you review is not the plan that applies. The pull request’s plan is “speculative so it cannot modify infrastructure”. At merge, the apply workflow “uploads the Terraform configuration” again and plans again, against whatever changed in between.

The apply is unattended, too. It is confirmed on its own, with no one reading the plan that runs and nothing checking the providers it loads. An unexpected replacement leads to an outage, and the alert is how you hear of it.

Here Turf runs beside the agent in a GitHub Agentic Workflow. The agent reviews every pull request. After the merge it compares the new plan with the one you reviewed, approves that exact plan under your policy, and stays through every round. The apply is attended by the agent.

What you stop worrying about.

Four things a platform engineer no longer checks by hand. Each line is the agent’s own, from a run on 2026-10-31.

01 · Approved as that exact plan

The plan you reviewed is the plan that runs.

At merge the agent plans again, compares with the plan on the pull request, and approves that exact plan or refuses with the difference. Production’s plan is judged on its own, under the stricter policy. Matches the reviewed plan: the changes and updates are the same as in the earlier plan comment.

02 · A turf action, answered with curl

The apply is attended by the agent.

The Terraform configuration asks the agent to verify the rollout from inside the apply. It fetches every function, checks the answer, and the engine goes on, or halts, says why, and the fix is a pull request. GET …533apcrq… → 200, message "Hello from staging!", environment "staging"

03 · One paragraph per Environment

Your policy is a paragraph, and every verdict quotes it.

In the repository, read by the agent on every run; changing the policy is a pull request. Refused under the staging approval rule (policy/approval.md): the plan would destroy the shared execution role aws_iam_role.lambda_exec.

04 · Checked before anything opens

A vulnerable provider never gets as far as a plan.

Every provider is checked against GitHub’s Advisory Database, through the GitHub MCP Server, at the version the lock file pins. hashicorp/vault 5.4.0 has a high-severity advisory (GHSA-gmm6-j2g5-r52m / CVE-2025-13357) … Nothing was opened or planned.

Part I is the host: GitHub Agentic Workflows, and Turf on the runner. Part II walks the pipeline, one stop at a time. Part III is what it guarantees.

What’s inside.

Eight chapters in three parts, a page on the Turf engine, every transcript from a real run, and the repository to fork.

Part I · The host

1GitHub Agentic Workflows
2Turf on the runner

Part II · The loop

3A review on every pull request
4Policy in plain language
5A well-governed apply
6Verified from inside
7Policy enforcement

Part III · The guarantees

8Safety, in layers
The Turf engine

Run it.

The pipeline in the paper is public, at github.com/turfbuild/turf-agentic-workflows: three workflows, two rules, and a setup/ directory that builds the demonstration environment as Terraform. Turf is available now, as a download. No form, no login. Free for noncommercial use; commercial use, including a company’s internal use, requires a license, and companies evaluate Turf under a free pilot.

Read the PDF Get started Licensing

Also from Turf: Metal to Tokens, a reference architecture for managed GPU cloud infrastructure, for neocloud providers.

GitHub, GitHub Actions, GitHub Copilot and GitHub Agentic Workflows are trademarks of GitHub, Inc. AWS and AWS Lambda are trademarks of Amazon.com, Inc. or its affiliates. Claude is a trademark of Anthropic, PBC. HashiCorp Vault is a trademark of HashiCorp, Inc. Each is named here only to describe interoperability; quotations from HashiCorp’s tutorial, OpenTofu’s documentation and GitHub’s documentation are attributed in the paper. Turf is not affiliated with, endorsed by, or sponsored by any of them. All other marks belong to their owners.