What the agent does
Terraform module CI rarely fails in one place, so the agent first works out which job and which Terraform version went red. In terraform-aws-modules/terraform-aws-vpc, .github/workflows/pre-commit.yml has a collectInputs job that lists the module's directories, then a preCommitMinVersions matrix that runs only terraform_validate in each directory on the lowest Terraform the code allows, and a preCommitMaxVersion job that runs every hook on the newest. The agent reads gh run view <id> --log-failed and notes the job name, the directory from the matrix (such as examples/complete or modules/vpc-endpoints) and the Terraform version in the step title.
Next it installs the matching toolchain in its sandbox. The minimum comes from required_version = ">= 1.0" in versions.tf, and the AWS provider constraint is version = ">= 6.28", so a resource argument added in a newer provider can pass on the max job and fail validation on the min job, or the reverse. The workflow pins TFLINT_VERSION: v0.64.0 and TERRAFORM_DOCS_VERSION: v0.24.0, and .pre-commit-config.yaml pins antonbabenko/pre-commit-terraform at v1.108.1. The agent installs those exact versions so its results match the runner's.
Then it reproduces the failure. For a validate error it runs terraform init -backend=false and terraform validate in the failing directory, which needs no AWS credentials. For a lint error it runs the terraform_tflint hook with the same --only rules the config lists, such as terraform_documented_variables, terraform_typed_variables and terraform_unused_declarations. A terraform_docs failure means the inputs and outputs table between <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> in README.md no longer matches variables.tf and outputs.tf; a terraform_wrapper_module_for_each failure means the files under wrappers/ are stale.
The fix goes where the error points. In a 1,543-line main.tf with seven aws_subnet resources (public, private, database, redshift, elasticache, intra, outpost), that is often one argument on one subnet resource, a variable in variables.tf with no type or description, or an output with no description. Generated files are regenerated by the hook, never edited by hand. The agent reruns pre-commit run -a until every hook passes, then opens a pull request against the failing branch.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "The Pre-Commit workflow failed on the branch feat/subnet-tags. Find the failed run with `gh run list --branch feat/subnet-tags --status failure --limit 1` and read it with `gh run view <run id> --log-failed`. Note which job failed (min or max Terraform version), which directory, and which hook. Install the same Terraform version, TFLint v0.64.0, terraform-docs v0.24.0 and pre-commit-terraform v1.108.1. Reproduce with `terraform init -backend=false && terraform validate` in that directory, or with the failing pre-commit hook. Fix the cause in the .tf files; let terraform_docs and the wrapper hook regenerate README.md and wrappers/ rather than editing them by hand. Do not run terraform plan or apply and do not use AWS credentials. Confirm `pre-commit run -a` passes, then open a pull request against feat/subnet-tags that quotes the error.",
"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.prix.dev/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 against the failing branch. Its diff has the .tf change that fixes the error, and, when a hook regenerated them, the updated README.md docs table and files under wrappers/. The description says which job failed, on which Terraform version and in which directory, quotes the validate or lint message, and lists the commands it ran to confirm the fix.
Pushing the branch runs pre-commit.yml again, so the pull request's checks show both the min-version matrix and the max-version job. That matters for a module whose constraints span from Terraform 1.0 upward: a fix that only passes on the newest Terraform shows up red on the min job before anyone merges it.
A reviewer checks that a new argument is supported by the lowest AWS provider version versions.tf allows, or that the constraint was raised on purpose and noted for the changelog, and that the regenerated docs match the variables they describe. No plan or apply ran, so nothing in an AWS account changed.
Run it on every pre-commit workflow failure
Add an automation to the Project that holds the module, with this prompt and a GitHub trigger on workflow_run.failure. Each failed run of the workflow starts one Rush run with the event after the prompt, so the agent gets the run id and branch without listing runs first. CI runs from forks never fire, which keeps outside contributors' pull requests from starting agents.
Modules in one organization often share the same pre-commit setup, so the same automation prompt works in each module's Project. Give the API key a webhook URL and Rush POSTs run.completed with the session_url when a turn finishes, so a bot can post the fix's link next to the failed check.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
Reproducing module CI on a laptop means installing the exact minimum and maximum Terraform versions, TFLint, terraform-docs and the pre-commit-terraform hooks, often in different versions from the ones your other projects use. In a Rush sandbox the agent installs exactly what the workflow pins, with its own clone, and leaves your local Terraform and plugin cache untouched.
The output is checkable. Every terraform validate and hook run is kept with its output, the pull request reruns both the min and max jobs, and the prompt rules out plan, apply and cloud credentials, so the run's reach is the repository and nothing else. When a provider release breaks validation across a dozen modules, each module's failure starts its own run, and they run at the same time.
Frequently asked questions
Does the agent need AWS credentials?
No. terraform init -backend=false and terraform validate check the configuration without contacting AWS, and the pre-commit hooks are static checks. The prompt forbids plan and apply, so the run never needs an account.
Why did validate pass for me and fail in CI?
Usually because CI runs the lowest Terraform version your required_version allows, and you run a newer one. The agent installs the version named in the failed step's title, so it sees the same error the runner did.
Will it edit the generated README table by hand?
No. It runs the terraform_docs hook, which rewrites the section between the BEGIN_TF_DOCS and END_TF_DOCS markers from your variables and outputs. Hand edits there would be overwritten by the next run of the hook anyway.
Can it fix a failure in an example directory?
Yes. The min-version job validates each directory separately, so a failure in examples/ipv6-dualstack or examples/complete names that directory. The agent runs validate there, fixes the example or the module input it uses, and reruns the hook for that directory.