A Github action for generating terraform module documentation using terraform-docs and gomplate. In addition to statically defined directory modules, this module can search specific sub folders 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.

v1.0.8

Using terraform-docs v0.9.1, which is supported and tested on terraform version 0.11+ & 0.12+ but may work for others.

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@v2
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs inside the USAGE.md and push changes back to PR branch
      uses: Dirrk/[email protected]
      with:
        tf_docs_working_dir: .
        tf_docs_output_file: USAGE.md
        tf_docs_output_method: inject
        tf_docs_git_push: 'true'

In addition to the below notes, further documentation on terraform-docs can be found here

This will just print the generated file

This will create/replace the tf_docs_output_file at the determined module path(s)

Instead of replacing the output file, this will inject the generated documentation into the existing file between the predefined delimeters: <!--- BEGIN_TF_DOCS ---> and <!--- END_TF_DOCS --->. If the file exists but does not contain the delimeters, the action will fail for the given module. If the file doesn't exist, it will create it using the value tf_docs_template which MUST have the delimeters.

To enable you need to ensure a few things first:

• set tf_docs_git_push to 'true'
• use actions/checkout@v2 with the head ref for PRs or branch name for pushes

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

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

• document - long form document
• table - github formatted table
• json - pure json output

- name: Generate TF Docs
  uses: Dirrk/[email protected]
  with:
    tf_docs_working_dir: .
    tf_docs_output_file: README.md

- name: Generate TF Docs
  uses: Dirrk/[email protected]
  with:
    tf_docs_working_dir: .,example1,example3/modules/test
    tf_docs_output_file: README.md

- name: Generate TF docs
  uses: Dirrk/[email protected]
  with:
    tf_docs_atlantis_file: atlantis.yaml

- name: Generate TF docs
  uses: Dirrk/[email protected]
  with:
    tf_docs_find_dir: examples/

Complete examples can be found here