All jobs

Add Pre-commit Hooks With fmt, validate, tflint and terraform-docs to a Terraform Repo

Yes. An agent adds a pre-commit setup that runs terraform fmt, validate, tflint and terraform-docs on your Terraform repo, runs it once, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the configuration and what already checks it. In a repository like hashicorp-education/learn-terraform-provision-eks-cluster there are four .tf files and nothing else that runs: terraform.tf requires Terraform ~> 1.3 and pins hashicorp/aws at ~> 5.47.0 with random, tls and cloudinit; main.tf wires the terraform-aws-modules/vpc/aws module at 5.8.1, the eks module at 20.8.5 and an iam-assumable-role-with-oidc module at 5.39.0 for the EBS CSI driver; variables.tf has one region variable and outputs.tf four outputs. .terraform.lock.hcl is committed, so terraform init installs the recorded provider versions, and there is no .github/ directory, no .pre-commit-config.yaml, no .tflint.hcl, and a two-line README that documents none of the inputs or outputs.

It writes .pre-commit-config.yaml with two hook sources. From pre-commit/pre-commit-hooks come end-of-file-fixer, trailing-whitespace and check-yaml; the first run of trailing-whitespace matters here because two comment lines in main.tf end in a space. From antonbabenko/pre-commit-terraform come terraform_fmt, terraform_validate, terraform_tflint and terraform_docs. The validate hook initialises the directory without a backend before it validates, which is what lets it run on a laptop with no AWS credentials; the agent adds --hook-config=--retry-once-with-cleanup=true so a stale .terraform directory is cleared and retried rather than failing the commit. The tflint hook gets --args=--config=__GIT_WORKING_DIR__/.tflint.hcl, and a new .tflint.hcl enables the aws ruleset plugin with the terraform ruleset's recommended preset, so checks like unused declarations and invalid instance types run against the two node groups of t3.small instances in main.tf.

terraform_docs needs markers to write between, so the agent adds <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> to README.md under the existing tutorial link and runs the hook once, which generates the requirements, providers, modules, inputs and outputs tables from the real files: the region input with its us-east-2 default, the cluster_endpoint, cluster_security_group_id, region and cluster_name outputs, and the three module calls with their versions. A .github/workflows/pre-commit.yml runs pre-commit run --all-files on every pull request with Terraform, tflint and terraform-docs installed on the runner, so the hooks are not only local.

The proof is one full run in the sandbox. The agent installs pre-commit, a Terraform matching required_version, tflint and terraform-docs, runs pre-commit run --all-files, and reads what changed: whitespace fixes, any reformatting terraform fmt applied, the generated README section, and any tflint finding, which it either fixes when the fix is plain or lists in the pull request with the rule name. Nothing is applied against AWS and no state is touched; validate with no backend is the deepest Terraform step.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add pre-commit hooks to this Terraform repository. Read terraform.tf, main.tf, variables.tf, outputs.tf, .terraform.lock.hcl, .gitignore and README.md first. Write .pre-commit-config.yaml using pre-commit/pre-commit-hooks for end-of-file-fixer, trailing-whitespace and check-yaml, and antonbabenko/pre-commit-terraform for terraform_fmt, terraform_validate with retry-once-with-cleanup, terraform_tflint pointed at a repository .tflint.hcl, and terraform_docs. Write .tflint.hcl enabling the terraform recommended preset and the aws ruleset plugin. Add BEGIN_TF_DOCS and END_TF_DOCS markers to README.md and let the hook generate the tables. Add a GitHub Actions workflow that runs pre-commit run --all-files on pull requests with terraform, tflint and terraform-docs installed. Install the tools, run pre-commit run --all-files, fix what the hooks change or report, run again until it passes, and open a pull request that lists every finding. Do not run terraform plan or apply.",
  "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 on its own branch with .pre-commit-config.yaml, .tflint.hcl, .github/workflows/pre-commit.yml, the README with its generated section, and whatever the hooks changed in the .tf files, which for whitespace is a few characters. .terraform.lock.hcl, the module versions and the variable default are unchanged.

The description shows the final pre-commit run --all-files output with every hook passing, lists each finding the first run produced and what was done about it, and pastes the generated README tables so a reviewer sees the inputs and outputs the documentation now carries. The install and run commands are in the transcript at GET /o/{org}/sessions/{id}/messages.

Before merging, a reviewer runs pre-commit install locally so the hooks fire on their own commits, checks the tflint rules they want on or off in .tflint.hcl, and decides whether terraform_docs should also update the README on every commit or only in CI. A follow-up message to the same session can add terraform_trivy or terraform_checkov to the same config.

Run it on every terminal hand-off

A platform engineer who wants this in every Terraform repository starts one run per repository from the terminal with this body, changing only the repository URL. Each run reads that repository's own providers, modules and README and produces a configuration that fits it, in its own sandbox.

Send a request_id, a UUID, with each body so a retried start returns the run it already began. The pull request is on the run's GET /o/{org}/sessions/{id} answer when it is open.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The hard part of this job is not writing the YAML, it is proving that the hooks pass on the real code with the real tools installed, which means a Terraform of the right version, a tflint with the AWS plugin downloaded, and a terraform init that fetches the pinned providers. The agent does that once in a clean sandbox and ships the result with the run log, so the first commit after merge does not fail on a surprise finding.

The pull request carries the final hook output and the first run's findings side by side, so a reviewer sees what the hooks will catch from now on. Many repositories can be done at once, each in its own sandbox, each with one pull request.

Frequently asked questions

Does the validate hook need AWS credentials?

No. It initialises without a backend, so providers are downloaded and the configuration is checked for internal consistency without contacting AWS or reading state. The lock file keeps the provider versions the repository already uses.

Will terraform-docs rewrite my whole README?

Only the text between the two markers the agent adds. The tutorial link above them stays, and anything written below the end marker is left alone. The generated tables are regenerated from the .tf files on every run, which is the point.

What does tflint check that validate does not?

Rules rather than syntax: the terraform ruleset flags unused declarations, deprecated syntax and missing version constraints, and the aws plugin knows the provider's resource arguments, for example whether an instance type exists. terraform validate only knows the configuration is well formed.

Why also run it in GitHub Actions?

pre-commit install is per clone, and a contributor who skips it can still push. The workflow runs the same pre-commit run --all-files on every pull request with the same tools, so the hooks are the gate either way.

Can I add security scanning later?

Yes. The same hook source provides terraform_trivy and terraform_checkov; adding either is one more entry in .pre-commit-config.yaml plus the tool on the CI runner, which a follow-up message to the session can do.

More Terraform jobs

The same job on other stacks

Keep reading