# The terraform-docs GitHub Action: A Complete CI Setup Guide

> Originally published on [DevToolHub](https://devtoolhub.com/terraform-docs-github-action/).

The [terraform-docs GitHub Action](https://terraform-docs.io/how-to/github-action/) generates a Markdown table of every input, output, and variable in a Terraform module, and commits it into your `README.md` on every pull request. The official docs page shows one example and stops — no full input list, no config-file setup, nothing about the failure mode that catches almost everyone on their first real repo.

## The real input list

The official example sets 4 inputs. The action actually has 18 — the full set, straight from the repo: `working-dir`, `output-file`, `output-format`, `output-method`, `config-file`, `atlantis-file`, `find-dir`, `recursive`, `recursive-path`, `fail-on-diff`, `git-push`, `git-commit-message`, `git-push-user-name`, `git-push-user-email`, `git-push-sign-off`, `template`, `indention`, `args`. `fail-on-diff` is ignored the moment `git-push` is true — you get one mode, not both.

## Auto-commit needs the right checkout ref

```yaml
- uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.ref }}
```

Skip that `ref` override and checkout lands on a detached-HEAD merge commit — a synthetic ref that goes nowhere real. `git-push: true` has nothing to push to without it.

## The gotcha the docs never mention

GitHub's own workflow-syntax docs: on a `pull_request` "from a forked repository," the `GITHUB_TOKEN`'s "permissions are adjusted to change any write permissions to read only" — no matter what your `permissions:` block says. Auto-commit fails on every external contribution's PR, full stop. Either switch to `fail-on-diff` for those, or use `pull_request_target` (only if the job never checks out untrusted fork code for anything beyond running `terraform-docs`).

## Multi-module repos

`recursive: true` (with `recursive-path`, default `modules`) picks up every submodule automatically. `atlantis-file` reuses an existing `atlantis.yaml`. `find-dir` runs a plain `find` for `.tf` files. Pick based on what you've already got in place.

Full breakdown with the complete config-file setup: [devtoolhub.com/terraform-docs-github-action](https://devtoolhub.com/terraform-docs-github-action/)