# Generate Terraform Module Docs With terraform-docs and Keep Them Current in CI

Yes. An agent adds terraform-docs to your module, injects the inputs, outputs, providers and resources into the README, and fails CI when the docs go stale.

[Run this on Rush](https://cloud.getrush.ai/run/add-terraform-docs/terraform/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the configuration before it generates anything. In a module like hashicorp-education/learn-terraform-provision-eks-cluster, `terraform.tf` requires Terraform `~> 1.3` and four providers: `hashicorp/aws ~> 5.47.0`, `hashicorp/random ~> 3.6.1`, `hashicorp/tls ~> 4.0.5` and `hashicorp/cloudinit ~> 2.3.4`, with a commented-out `cloud` block. `variables.tf` declares one variable, `region`, a string defaulting to `us-east-2` with a description. `outputs.tf` has four outputs with descriptions: `cluster_endpoint`, `cluster_security_group_id`, `region` and `cluster_name`. `main.tf` has the `aws` provider, a `data "aws_availability_zones"` filtered on `opt-in-status`, a `random_string.suffix` of length 8, and three registry modules: `terraform-aws-modules/vpc/aws` `5.8.1`, `terraform-aws-modules/eks/aws` `20.8.5` with `cluster_version = "1.36"` and two `t3.small` managed node groups, and `terraform-aws-modules/iam/aws//modules/iam-assumable-role-with-oidc` `5.39.0` for the EBS CSI driver. `README.md` is four lines pointing at the tutorial, there is no `.github` directory, and `.terraform.lock.hcl` also pins `null` and `time`, which the modules pull in.

The agent installs the terraform-docs release binary in the sandbox and runs `terraform-docs markdown table .` once to see what it produces for this module: a Requirements table (terraform and the four providers with their constraints), a Providers table (`aws` and `random`, the ones used directly), a Modules table (`eks`, `irsa-ebs-csi`, `vpc` with source and version), a Resources table listing `random_string.suffix`, `data.aws_availability_zones.available` and `data.aws_iam_policy.ebs_csi_policy` with links to the provider docs, an Inputs table with `region`, and an Outputs table with the four outputs and their descriptions. It compares that against the files to confirm nothing is missing, which is also how it notices a variable or output with no `description`, and there are none here.

Then it writes `.terraform-docs.yml` at the root: `formatter: "markdown table"`, `output: {file: README.md, mode: inject, template: ...}` with the `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->` markers, `sort: {enabled: true, by: required}`, and `settings: {anchor: false}` so headings stay plain. It adds the two markers to `README.md` below the existing paragraph, runs `terraform-docs .` so the tables appear between them, and runs `terraform fmt -check` and `terraform init -backend=false` followed by `terraform validate` to be sure the configuration it documented parses with the pinned providers.

Finally it adds `.github/workflows/terraform-docs.yml`. On `pull_request` the job runs `terraform-docs/gh-actions` with `working-dir: .`, `config-file: .terraform-docs.yml`, `output-file: README.md`, `output-method: inject` and `fail-on-diff: true`, so a pull request that adds a variable without regenerating the README fails with the diff in the log. On `push` to `main` the same action runs with `git-push: true` and a fixed commit message, so the default branch never drifts even when a contributor forgets. The workflow gets `permissions: contents: write` for that job only and `contents: read` elsewhere. The agent changes no `.tf` file.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add terraform-docs to this Terraform configuration. Read every .tf file first and list the variables, outputs, providers, modules and resources you find. Add a .terraform-docs.yml using the markdown table formatter with inject mode into README.md, keep the README's existing text, and generate the documentation between the markers. Run terraform fmt -check and terraform validate without a backend. Add a GitHub Actions workflow that fails a pull request when the generated docs differ from the committed README, and that regenerates and commits the README on pushes to the default branch. Do not change any .tf file. If any variable or output lacks a description, list it in the pull request rather than inventing one.",
  "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 that adds `.terraform-docs.yml` and `.github/workflows/terraform-docs.yml` and changes `README.md`, which now carries the six generated tables between the markers under the original text. The description shows the Inputs and Outputs tables inline, quotes the `terraform validate` result from the sandbox, and lists any variable or output without a description, so the reviewer can write those rather than have a generator guess.

The run's record keeps every command with its output, including the terraform-docs version installed, the first dry run, the `terraform init -backend=false` provider download and the validation, so a reviewer can confirm the tables were produced from this configuration and not typed.

Before merging, a reviewer checks the generated Resources links point at the right provider versions, decides whether the push job should commit to `main` directly or open its own pull request (a protected branch needs the latter), and confirms the workflow's write permission is acceptable for the repository.

## Run it on every new Terraform module

Each new module or root configuration in your organisation gets the same treatment with one `POST /o/{org}/sessions` carrying this body and that repository in `resources`. Started from a terminal, the run continues in its sandbox after you close the window; the sandbox parks when the turn ends and a follow-up (`POST /o/{org}/sessions/{id}/messages`) can switch the formatter or add a section without starting over.

A webhook on the API key reports `run.completed` with the `session_url` to read the pull request link, so a script that loops over repositories needs no polling.

## Why run it on Rush?

The hard part of module documentation is not the generator but the drift after it: a variable added in a hurry, a README that still shows last quarter's outputs. The agent sets up the check that catches the drift and the job that repairs it, and it runs the generator and `terraform validate` in its own sandbox first, so the README in the pull request is produced from the configuration, with the output kept as proof.

No cloud credentials are involved: `terraform init -backend=false` downloads providers and `terraform validate` checks the configuration without touching an account. Several modules can be documented at once, each in its own sandbox, each with its own pull request.

## Frequently asked questions

### Will it overwrite my README?

No. Inject mode writes only between the `BEGIN_TF_DOCS` and `END_TF_DOCS` markers. The text above and below them is yours, and the agent adds the markers below your existing content rather than at the top.

### Does it need AWS credentials?

No. terraform-docs reads the `.tf` files directly. The validation step uses `terraform init -backend=false`, which downloads providers but configures no backend, and `terraform validate`, which never contacts a cloud API.

### What if a variable has no description?

terraform-docs leaves the description cell empty and the agent lists the variable in the pull request. It does not write descriptions for you, because a wrong description in generated docs is worse than a blank one. A follow-up can add them once you supply the wording.

### Can it document a repository with several modules?

Yes. Say where they are, or let the agent find every directory with a `.tf` file. It adds a `recursive` setting or one workflow matrix entry per module, and each module's README gets its own markers.

## More Terraform jobs

- [Add TFLint and Format Checks to Terraform CI](https://getrush.ai/run/add-tflint-to-ci/terraform/)
- [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/)

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

- [Shard Cypress Specs Across CI Containers Without Cypress Cloud](https://getrush.ai/run/add-test-sharding/cypress/)
- [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/)

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