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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.