# Post Terraform Plan Comments on Pull Requests

Yes. An agent adds a GitHub Actions workflow that runs fmt, validate and plan on every pull request and posts the plan as one updated comment, then opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-plan-comments-to-pr/terraform/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the configuration before it writes a workflow, because what `terraform plan` needs depends on the providers, the backend and the version pins. In a root module like hashicorp-education/learn-terraform-provision-eks-cluster, `terraform.tf` requires Terraform `~> 1.3` and pins `hashicorp/aws` at `~> 5.47.0`, `random` at `~> 3.6.1`, `tls` at `~> 4.0.5` and `cloudinit` at `~> 2.3.4`, with a `cloud {}` block commented out; `.terraform.lock.hcl` is committed with `aws` resolved to `5.47.0`. `main.tf` builds a VPC with `terraform-aws-modules/vpc/aws` `5.8.1`, an EKS cluster with `terraform-aws-modules/eks/aws` `20.8.5` and two managed node groups of `t3.small`, and an IRSA role for the EBS CSI driver; `variables.tf` has one variable, `region`, defaulting to `us-east-2`. There is no `.github` directory, and `.gitignore` already excludes `*.tfplan` and `*.tfvars`.

The agent writes `.github/workflows/terraform-plan.yml` triggered on `pull_request`, with `permissions` of `contents: read`, `pull-requests: write` and `id-token: write`, a `concurrency` group per pull request so a new push cancels the previous plan, and one job that checks out, installs Terraform with `hashicorp/setup-terraform` at the version `terraform.tf` allows, assumes an AWS role through `aws-actions/configure-aws-credentials` with `role-to-assume` read from a repository variable (OpenID Connect, no long-lived keys in secrets), and runs `terraform fmt -check -recursive`, `terraform init -input=false`, `terraform validate` and `terraform plan -no-color -input=false -out=tfplan`, each with `continue-on-error` so the comment can report every step rather than stop at the first.

The comment is one `actions/github-script` step. It looks for an existing comment on the pull request that starts with a hidden marker, builds a body with a pass or fail line for `fmt`, `init`, `validate` and `plan`, the plan's summary line, and the full `-no-color` plan inside a `<details>` block, truncates to stay under GitHub's comment size limit with a note when it does, and updates the existing comment or creates one. A final step fails the job if `fmt`, `init` or `validate` failed, after the comment is posted, so the check and the comment agree. `terraform apply` is not in the workflow; the agent says so in the description.

Because the `cloud {}` block is commented out and there is no `backend` block, state is local, which means a plan in CI runs against empty state and would propose creating everything. The agent writes that plainly in the pull request and in a comment at the top of the workflow, with the two lines to change once the team picks remote state: the `cloud` block with `TF_API_TOKEN` passed to `setup-terraform` as `cli_config_credentials_token`, or an S3 backend with the same role. In its sandbox the agent installs Terraform, runs `terraform fmt -check`, `terraform init -backend=false` and `terraform validate` against the committed lockfile, which need no AWS credentials, and runs `actionlint` over the new workflow, and includes the output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a GitHub Actions workflow that posts the Terraform plan on every pull request. Read terraform.tf, main.tf, variables.tf, outputs.tf, .terraform.lock.hcl and .gitignore first and note whether there is a backend or cloud block. Write .github/workflows/terraform-plan.yml on pull_request with least-privilege permissions (contents read, pull-requests write, id-token write), a concurrency group per pull request, Terraform installed at the version the configuration allows, AWS credentials from an OpenID Connect role named in a repository variable, and steps for terraform fmt -check, init, validate and plan -no-color -out=tfplan, each with continue-on-error. Add a github-script step that creates or updates a single comment with a hidden marker, showing each step's result and the plan inside a details block, truncated under GitHub's comment limit. Fail the job after the comment if fmt, init or validate failed. Do not add apply. If state is local, say so in the workflow and the pull request and show how to switch to remote state. In the sandbox run terraform fmt -check, terraform init -backend=false, terraform validate and actionlint, include the output, and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `.github/workflows/terraform-plan.yml` and nothing else; `main.tf`, `terraform.tf`, `variables.tf`, `outputs.tf` and `.terraform.lock.hcl` are untouched. The description names the repository variable the role ARN must be stored in and the trust policy the role needs for GitHub's OIDC provider, and states that plan in CI will run against empty state until a backend is chosen.

The description also quotes the `terraform fmt -check`, `terraform init -backend=false`, `terraform validate` and `actionlint` output from the sandbox. The full output is in the transcript at `GET /o/{org}/sessions/{id}/messages`. The new workflow runs on the pull request that adds it, so its first plan comment appears there once the variable is set.

Before merging, a reviewer creates the OIDC role with read-only access for plan, sets the variable, and decides on remote state. A follow-up message to the same session can add the `cloud` block or an S3 backend and a separate apply workflow on merge to `main`.

## Run it on every terminal hand-off

A platform engineer who wants this on every Terraform repository sends one `POST /o/{org}/sessions` per repository with this prompt as `input` and the repository in `resources`. Each run reads that repository's own `terraform.tf`, so a module with an S3 backend gets a plan that reads real state, a Terraform Cloud workspace gets `TF_API_TOKEN` wiring, and a bare tutorial like this one gets the local-state warning.

A `request_id` that is a UUID v5 of the repository's full name makes a retry return the run already started. The key's `webhook_url` reports `run.completed` with the `session_url`, so a handler can collect every pull request link into one list for review.

## Why run it on Rush?

A plan comment workflow is short but every line matters: the permissions, the OIDC trust, the exit codes under `continue-on-error`, the comment that must update rather than pile up, and the size limit that silently truncates a large plan. The agent writes it against the configuration's real provider pins and lockfile, validates what it can without credentials, and lints the workflow itself.

The pull request carries the validation output and a plain statement of what is still needed from the team, so a reviewer sets one variable and reads the first comment rather than debugging YAML in a loop of pushes. The same prompt runs across many repositories at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Does the workflow apply anything?

No. It runs `fmt`, `init`, `validate` and `plan` and posts the result; the saved `tfplan` is discarded with the runner. Apply on merge is a separate workflow with its own role and approvals, and a follow-up message can add it.

### What AWS credentials does it use?

A role assumed through GitHub's OpenID Connect provider, named in a repository variable and passed to `aws-actions/configure-aws-credentials`. No access key is stored in secrets. The role needs read access to everything the plan inspects; the pull request lists the trust policy condition that limits it to this repository.

### Why would the plan say it will create every resource?

Because this configuration has no backend and the `cloud` block is commented out, so CI starts with empty state. The workflow comment and the pull request say so, and show the two-line change to point at Terraform Cloud or S3 once the team has decided where state lives.

### What happens when the plan is bigger than a comment allows?

The script truncates the plan text to fit under GitHub's comment limit, keeps the summary line, and adds a note that the full plan is in the workflow logs. The step result lines are never truncated.

## More Terraform jobs

- [Add Pre-commit Hooks With fmt, validate, tflint and terraform-docs to a Terraform Repo](https://getrush.ai/run/add-pre-commit-hooks/terraform/)
- [Move Terraform State to a Remote S3 Backend](https://getrush.ai/run/add-remote-state/terraform/)
- [Add Renovate to a Terraform Module Repository](https://getrush.ai/run/add-renovate/terraform/)

## More jobs like this: Hand off a long task

- [Add PMD Static Analysis to a Maven Build](https://getrush.ai/run/add-pmd/maven/)
- [Add Pod Disruption Budgets to Argo CD Applications](https://getrush.ai/run/add-pod-disruption-budgets/argo-cd/)
- [Add Pod Disruption Budgets to a GKE App](https://getrush.ai/run/add-pod-disruption-budgets/gke/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
