terraform-docs-gh-actions

terraform-docs GitHub Actions

Generate Terraform module documentation in pull requests.

In addition to statically defined directory modules, this module can search specific subfolders or parse atlantis.yaml for module identification and doc generation. This action has the ability to auto commit docs to an open PR or after a push to a specific branch.

Version

v1.3.0 (uses terraform-docs v0.19.0, which is supported and tested on Terraform version 0.11+ and 0.12+ but may work for others.)

Upgrade v0 to v1

Release v1 contains following breaking changes:

default value of output-file has been changed to README.md

default value of template has been changed to

<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->

Usage

To use terraform-docs github action, configure a YAML workflow file, e.g. .github/workflows/documentation.yml, with the following:

name: Generate terraform docs
on:
  - pull_request
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs inside the README.md and push changes back to PR branch
      uses: terraform-docs/gh-actions@v1.3.0
      with:
        working-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

NOTE: If `output-file` (default README.md) already exists it will need to be updated, with the block delimeters `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->`, where the generated markdown will be injected. Otherwise the generated content will be appended at the end of the file.

NOTE: If `output-file` (default README.md) doesn't exist it will created and the content will be saved into it.

Configuration

Inputs

Name	Description	Default	Required
args	Additional arguments to pass to the command (see full documentation)	`""`	false
atlantis-file	Name of Atlantis file to extract list of directories by parsing it. To enable, provide the file name (e.g. `atlantis.yaml`)	`disabled`	false
config-file	Name of terraform-docs config file. To enable, provide the file name (e.g. `.terraform-docs.yml`)	`disabled`	false
fail-on-diff	Fail the job if there is any diff found between the generated output and existing file (ignored if `git-push` is set)	`false`	false
find-dir	Name of root directory to extract list of directories by running `find ./find\_dir -name \*.tf` (ignored if `atlantis-file` is set)	`disabled`	false
git-commit-message	Commit message	`terraform-docs: automated action`	false
git-push	If true it will commit and push the changes	`false`	false
git-push-sign-off	If true it will sign-off commit	`false`	false
git-push-user-email	If empty the no-reply email of the GitHub Actions bot will be used (i.e. `github-actions[bot]@users.noreply.github.com`)	`""`	false
git-push-user-name	If empty the name of the GitHub Actions bot will be used (i.e. `github-actions[bot]`)	`""`	false
git-sub-dir	Subdirectory that terraform code is checked out into	`""`	false
indention	Indention level of Markdown sections [1, 2, 3, 4, 5]	`2`	false
output-file	File in module directory where the docs should be placed	`README.md`	false
output-format	terraform-docs format to generate content (see all formats) (ignored if `config-file` is set)	`markdown table`	false
output-method	Method should be one of `replace`, `inject`, or `print`. Set as an empty string if `output.mode` and `output.file` are defined in config-file	`inject`	false
recursive	If true it will update submodules recursively	`false`	false
recursive-path	Submodules path to recursively update	`modules`	false
template	When provided will be used as the template if/when the `output-file` does not exist. Set as an empty string if `output.template` is defined in config-file	`<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->`	false
working-dir	Comma separated list of directories to generate docs for (ignored if `atlantis-file` or `find-dir` is set)	`.`	false

Output Method (output-method)

print

This will just print the generated output
replace

This will create or replace the output-file at the determined module path(s)
inject

Instead of replacing the output-file, this will inject the generated documentation into the existing file between the predefined delimeters:  and . If the file exists but does not contain the delimeters, the action will append the generated content at the end of output-file. If the file doesn't exist, it will create it using the value template which MUST have the delimeters.

Auto commit changes

To enable you need to ensure a few things first:

set git-push to true

use actions/checkout@v3 with the head ref for PRs or branch name for pushes

PR

on:
  - pull_request
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.ref }}

Push

on:
  push:
    branches:
      - master
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        ref: master

Outputs

Name	Description
num_changed	Number of files changed

Examples

Single folder

- name: Generate TF Docs
  uses: terraform-docs/gh-actions@v1.3.0
  with:
    working-dir: .

Multi folder

- name: Generate TF Docs
  uses: terraform-docs/gh-actions@v1.3.0
  with:
    working-dir: .,example1,example3/modules/test

Use `atlantis.yaml` v3 to find all directories

- name: Generate TF docs
  uses: terraform-docs/gh-actions@v1.3.0
  with:
    atlantis-file: atlantis.yaml

Find all `.tf` file under a given directory

- name: Generate TF docs
  uses: terraform-docs/gh-actions@v1.3.0
  with:
    find-dir: examples/

Recursively under a given directory

- name: Generate TF docs
  uses: terraform-docs/gh-actions@v1.3.0
  with:
    working-dir: examples/
    recursive: true
    recursive-path: modules

Complete examples can be found here.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Action

terraform-docs-gh-actions