PlanGuard - Keeping the AI Out of the Terraform Verdict

Nobody really reads a Terraform plan

terraform plan output is long, and most of it is lines that don't change. A reviewer scrolls past and misses one destroy. So "let a model summarise the plan" is an idea that arrives on its own.

Draw the line wrong, though, and it gets dangerous. Ask a model to decide whether a change is safe and one day a database gets dropped on an afternoon it called safe.

So the two were separated

PlanGuard splits two responsibilities.

• Code decides. Policy, risk and pass/fail come from deterministic code, and the model cannot change them.
• The AI explains. Turning a plan with sensitive values removed into a readable summary is an optional assistant feature.

A badly written summary doesn't move the verdict. And when the code blocks a change, it stays blocked regardless of what the model says.

Why it's two jobs

The default workflow runs like this:

Create a plan from the trusted default branch
  → remove Terraform-marked sensitive values
  → store a short-retention sanitized artifact
  → create an AI explanation on a fresh runner

The job that runs Terraform never receives the AI API key. The job holding the AI API key never executes Terraform code or providers; it reads only the sanitized artifact.

One job would be simpler, but Terraform providers and modules are other people's code. Putting an AI key in the environment where that code runs creates a path for the key to leave. Two jobs removes the path.

No separate service

There's no hosted PlanGuard service, no Render deployment, no GitHub App. It runs inside your repository's own GitHub runner. The provider API key comes only from GitHub Actions secrets.

For most teams, handing cloud credentials to an outside service in order to review infrastructure is a request that fails on its own terms.

Using it

Create one secret in the Terraform repository and add a workflow.

PLANGUARD_AI_API_KEY

Use a key for OpenAI or an OpenAI-compatible provider. Never put it directly in workflow YAML, Terraform variables, commits, issues or logs. For cloud authentication, prefer a short-lived, environment-protected OIDC identity with plan-only permissions.

• GitHub
• planguard.theorvane.tech