What the agent does
The agent reads the configuration before writing YAML. In a repository like hashicorp-education/learn-terraform-provision-eks-cluster there is no .github/ directory at all. terraform.tf sets required_version to ~> 1.3 and pins the aws provider at ~> 5.47.0, random at ~> 3.6.1, tls at ~> 4.0.5 and cloudinit at ~> 2.3.4; .terraform.lock.hcl is committed and records aws 5.47.0, cloudinit 2.3.4, null 3.2.2, random 3.6.1, time 0.11.1 and tls 4.0.5. main.tf wires the terraform-aws-modules/vpc/aws module at 5.8.1, terraform-aws-modules/eks/aws at 20.8.5 with cluster_version 1.36 and two managed node groups, and the iam-assumable-role-with-oidc submodule at 5.39.0 for the EBS CSI driver; variables.tf has one variable, region, defaulting to us-east-2, and .gitignore already excludes .terraform/, state files and *.tfvars.
From that it writes .github/workflows/terraform.yml with two jobs that need no AWS account. The validate job checks out the code, installs Terraform with hashicorp/setup-terraform at a version inside the ~> 1.3 constraint, runs terraform fmt -check -recursive -diff, then terraform init -backend=false -input=false and terraform validate. Init without a backend still downloads the three registry modules and the six locked providers, which is what makes validate meaningful for a configuration built from modules, and the job caches TF_PLUGIN_CACHE_DIR keyed on the lock file so the provider download is paid once. The lint job installs tflint with terraform-linters/setup-tflint, adds a .tflint.hcl that enables the aws ruleset plugin, runs tflint --init and then tflint over the root module, so a deprecated argument or an invalid instance type in the node groups fails the check.
Two things in this repository need checking rather than assuming. The lock file carries provider hashes for the platform it was generated on; if it lacks linux_amd64 entries, terraform init on the runner refuses the providers, so the agent runs terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 and commits the widened lock file in the same pull request, saying so. And terraform plan needs AWS credentials and a backend, so the agent writes a commented plan job that would use aws-actions/configure-aws-credentials with an OIDC role, with the one variable region passed through, and explains in the pull request which repository settings make it live.
The proof is the same commands run in the sandbox first: terraform fmt -check, init -backend=false, validate and tflint all pass locally before the branch is pushed, and then the workflow runs on the pull request itself. If fmt reports a file, the agent formats it in the same pull request and lists it, since otherwise the first CI run would fail on code it did not write.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add GitHub Actions CI to this Terraform repository. Read terraform.tf, main.tf, variables.tf, outputs.tf, .terraform.lock.hcl and .gitignore first. Write .github/workflows/terraform.yml that runs on pull requests and pushes to the default branch with two jobs: one that installs Terraform at a version inside required_version, runs terraform fmt -check -recursive -diff, terraform init -backend=false -input=false with a plugin cache keyed on the lock file, and terraform validate; and one that installs tflint, adds a .tflint.hcl enabling the aws ruleset, runs tflint --init and tflint. Check whether the lock file has linux_amd64 hashes and widen it with terraform providers lock if it does not. Add a commented plan job that uses OIDC credentials and explain what it needs. Run every command in the sandbox first; if fmt reports files, format them and list them. Open a pull request and make the workflow pass on it.",
"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 on its own branch adding .github/workflows/terraform.yml and .tflint.hcl, plus .terraform.lock.hcl when the lock needed Linux hashes and any .tf file fmt reformatted. No resource, module version or variable changes.
The description lists each job and its steps, the Terraform version chosen and the constraint it satisfies, the ruleset tflint loaded, whether the lock file was widened and why, and the local output of the four commands. The workflow's own run on the pull request is the second proof, and the commands are in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer checks the Actions tab for the green run, decides whether to enable the commented plan job by creating the OIDC role and repository variable it names, and whether the workflow should also run on a schedule to catch provider deprecations between pull requests.
Run it on every Terraform repository without CI
Start one run per repository from your own server: POST /o/{org}/sessions with this prompt and that repository in resources, one call each. GET /o/{org}/github lists every repository the Rush GitHub App installation can reach, so a script can find the ones with .tf files and no .github/workflows/ directory and start a run for each. Each run has its own sandbox and its own branch.
Give the key a webhook_url and each run POSTs run.completed with its session_url when the turn finishes, so the pull request links collect on your side without polling. A key may have at most max_concurrent runs in progress at once, 4 by default, and a request past that answers 202 with status: "queued", so a script over many Terraform repositories sends them all together and Rush feeds the queued runs in as slots free.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Terraform CI fails for reasons that only show on the runner: a lock file without Linux hashes, a provider download that times out without a cache, a validate that needs modules init never fetched. On a laptop each is a push, a wait and a log read. In a Rush sandbox the agent runs the real terraform init against the registry, reads the lock file and fixes the cause before pushing, so the first run on the pull request is the one you see.
The result is a workflow with its own green run attached, and the step left out, plan, is written down with the credentials and settings it needs rather than silently skipped. Several repositories can be onboarded at once, each in its own sandbox and pull request.
Frequently asked questions
Does the workflow need AWS credentials?
No. fmt, init -backend=false, validate and tflint all run without a cloud account; init only talks to the Terraform registry for modules and providers. The plan job, which does need credentials, is included commented out with the OIDC setup it requires described in the pull request.
Why might the lock file change?
.terraform.lock.hcl records provider hashes per platform. If it was generated on a Mac and holds only darwin hashes, terraform init on an Ubuntu runner refuses the providers. The agent checks the file and, if needed, runs terraform providers lock for both platforms and commits the result, with a note in the description.
Which Terraform version does CI use?
One that satisfies the required_version constraint in terraform.tf, ~> 1.3 here, pinned explicitly in the workflow so a new release cannot change the result between runs. The pull request names the version and the constraint side by side.
What does tflint add over validate?
validate checks syntax and types; tflint with the aws ruleset checks provider-specific facts, such as an instance type that does not exist or an argument the provider deprecated. On this configuration that covers the node group instance types in main.tf and the module inputs.
More Terraform jobs
The same job on other stacks
- Add GitHub Actions CI to a Textual App (Textual)
- Set Up GitHub Actions CI for a Vapor App (Vapor)
- Set Up GitHub Actions CI for a VS Code Extension (VS Code Extension)