The terraform-docs GitHub Action: A Complete CI Setup Guide
Originally published on DevToolHub.
The terraform-docs 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
- 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