# Add TFLint and Format Checks to Terraform CI

Yes. An agent adds a pinned TFLint config with the provider ruleset and a terraform fmt check to the workflow that runs validate, fixes what they flag, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-tflint-to-ci/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 Terraform and the workflow that checks it. In a repository like GoogleCloudPlatform/microservices-demo, `terraform/` holds `main.tf`, `memorystore.tf`, `output.tf`, `providers.tf`, `variables.tf`, `terraform.tfvars` and a README. `providers.tf` pins `hashicorp/google` to an exact version in `required_providers` but sets no `required_version` for Terraform itself. `main.tf` enables four APIs through the `project-factory` module's `project_services` submodule at `~> 18.0`, creates an Autopilot `google_container_cluster` named `my_cluster`, fetches credentials through the `gcloud` module at `~> 4.0`, and applies the Kustomize manifests with two `null_resource` blocks running `kubectl` in `local-exec` provisioners. `memorystore.tf` adds a `google_redis_instance` named `redis-cart` and a third `null_resource` that runs `sed` against a kustomization file, both behind `count = var.memorystore ? 1 : 0`. `variables.tf` types and describes six variables, and `terraform.tfvars` ships with `<project_id_here>` as the project id.

`.github/workflows/terraform-validate-ci.yaml` runs on pushes to `main` and pull requests when `terraform/**` or the workflow itself changes, with `actions/checkout@v7`, `hashicorp/setup-terraform@v4` with no `terraform_version`, so whatever release is current, and two commands: `terraform init -backend=false` and `terraform validate`. `validate` catches a wrong argument or a missing variable; it does not catch a resource name that breaks the naming convention, a declared variable nobody reads, a provider argument the Google ruleset knows is invalid, or a file that `terraform fmt` would rewrite. The main `ci-pr.yaml` ignores the `terraform/` path entirely, and `.github/renovate.json5` is the only place dependency versions are managed.

The agent adds `terraform/.tflint.hcl` with the `terraform` ruleset on its `recommended` preset plus `terraform_naming_convention`, which the preset leaves off, and the `google` ruleset from `terraform-linters/tflint-ruleset-google` at a pinned version, then runs `tflint --init` and `tflint` in its sandbox and reads the findings. What it flags is fixed in the same pull request where the fix is safe: `terraform_required_version` wants a `required_version` constraint, so one is added to `providers.tf` matching the Terraform the agent validated with; `terraform_unused_declarations` is checked against each variable and local. A finding whose fix would change infrastructure is not applied: `terraform_naming_convention` objects to `redis-cart`, but renaming a resource address forces a replacement for anyone who has applied this module, so the rule is set to allow the existing name, with a comment, and the pull request explains. `terraform fmt -check -recursive -diff` is run too, and any file it would rewrite is formatted.

The workflow gains three steps ahead of validate: `terraform fmt -check -recursive -diff`, `terraform-linters/setup-tflint@v4` pinned to a TFLint version, and `tflint --init` followed by `tflint -f compact` with `GITHUB_TOKEN` in the environment so plugin downloads are not rate limited. `setup-terraform` gets a `terraform_version` so the run is reproducible, and `tflint --init` is cached on the `.tflint.hcl` hash. The agent runs the final sequence, `fmt -check`, `init -backend=false`, `validate`, `tflint`, from a clean checkout in the sandbox before opening the pull request, with the Google provider download that `init` performs included.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add TFLint and a terraform fmt check to the Terraform CI in this repository. Read every file under terraform/ and .github/workflows/terraform-validate-ci.yaml first, and note the provider pin, the module version constraints, the null_resource provisioners and the absence of a required_version. Write terraform/.tflint.hcl with the terraform ruleset on its recommended preset plus the naming convention rule, and the google ruleset at a pinned version. Run tflint --init and tflint in the sandbox, then fix what is safe to fix: add a required_version to providers.tf matching the Terraform you validated with, remove or justify unused declarations, and format any file terraform fmt -check reports. For any finding whose fix would change a resource address or force a replacement, configure the rule to allow the existing name with a comment and explain in the pull request. Extend the workflow with a terraform fmt -check -recursive -diff step, setup-tflint pinned to a TFLint version, tflint --init with GITHUB_TOKEN and a cache, and tflint -f compact, and pin terraform_version on setup-terraform. Run fmt -check, init -backend=false, validate and tflint from a clean checkout before opening a pull request that lists each finding and what was done with it.",
  "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

The pull request adds `terraform/.tflint.hcl`, changes `.github/workflows/terraform-validate-ci.yaml`, adds a `required_version` block to `providers.tf`, and reformats any file `fmt` reported. Resource addresses, variable names, module versions and the provider pin are unchanged, so a `terraform plan` against an existing deployment shows no infrastructure change from this pull request.

The description is a findings table: each TFLint rule that fired, the file and line, and whether it was fixed, allowed with a reason, or left for a follow-up, followed by the `fmt -check` result and the `validate` and `tflint` output from the clean sandbox run. The full commands are in the session transcript at `GET /o/{org}/sessions/{id}/messages`, and the workflow runs the new steps on the pull request itself.

Before merging, a reviewer confirms the `required_version` constraint matches the Terraform their team runs, reads the allowed naming finding and decides whether a renamed resource with a `moved` block is worth a later pull request, and checks the pinned TFLint and ruleset versions. A follow-up message to the same session can add the `.tflint.hcl` to the Renovate configuration so those pins are kept current.

## Run it on every terminal hand-off

A platform engineer who has seen one too many formatting-only diffs in Terraform reviews starts this from the terminal with this body and goes back to the cluster upgrade. The run reads the real module and the real workflow, so the rules it enables and the findings it fixes come from this code rather than from a generic checklist.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. When the run finishes, its `GET /o/{org}/sessions/{id}` answer names the pull request.

## Why run it on Rush?

Adding a linter to Terraform is mostly deciding what to do with its first findings, and that needs the linter run against the real module with the provider ruleset downloaded, then a judgment per finding about whether the fix touches infrastructure. The agent runs it in its own sandbox, reads each finding in the file it points at, and separates the safe fixes from the ones that would force a resource replacement.

Every `tflint`, `fmt` and `validate` run is kept with its output in the session record, so the findings table in the pull request is backed by the run that produced it. A team with several Terraform roots can send the same request for each at once and get one pull request per module, each with that module's own findings.

## Frequently asked questions

### Will TFLint fail the build on day one?

No. The agent runs it before opening the pull request and either fixes each finding or configures the rule to allow the existing code with a comment, so the first CI run on the pull request passes. New findings fail later pull requests, which is the point of the check.

### Why not rename redis-cart to satisfy the naming rule?

Because a resource address is state: renaming `google_redis_instance.redis-cart` would make Terraform destroy and recreate the instance for anyone who has applied this module, unless a `moved` block is added and reviewed. That is an infrastructure change, not a lint fix, so the agent allows the existing name and leaves the rename for a pull request of its own.

### Does this need Google Cloud credentials in CI?

No. `terraform init -backend=false` downloads the provider without a backend, `validate` and `fmt` never contact an API, and TFLint reads the configuration statically. The Google ruleset checks argument values against what the provider accepts, not against a project.

### What about the module version constraints and the provider pin?

They are left where they are. `~> 18.0`, `~> 4.0` and the exact Google provider version are the team's choices and are already covered by Renovate. TFLint's `terraform_module_pinned_source` rule only fires on git sources without a ref, which this module does not use.

## More Terraform jobs

- [Add Trivy Scanning to a Terraform Module's CI](https://getrush.ai/run/add-trivy-scan-to-ci/terraform/)
- [Add Variable Validation to a Terraform Module from a Linear Issue](https://getrush.ai/run/add-variable-validation/terraform/)
- [Estimate Cloud Costs for a Terraform Deployment](https://getrush.ai/run/compare-cloud-costs/terraform/)

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

- [Add TLS to a Tokio TCP Server](https://getrush.ai/run/add-tls/tokio/)
- [Add Topology Spread Constraints to Kubernetes Deployments](https://getrush.ai/run/add-topology-spread-constraints/kubernetes/)
- [Add towncrier Changelog Fragments to a Python Package](https://getrush.ai/run/add-towncrier-changelog/python/)

## 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/)
