Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
file-text

GitHub Action

terraform-docs

v1.0.5

terraform-docs

file-text

terraform-docs

A Github action for generating terraform module documentation using terraform-docs and gomplate

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: terraform-docs

              
  uses: Dirrk/terraform-docs@v1.0.5
Learn more about this action in Dirrk/terraform-docs

Choose a version

terraform-docs

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.

Version

v1.0.5

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

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@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/terraform-docs@v1.0.5
      with:
        tf_docs_working_dir: .
        tf_docs_output_file: USAGE.md
        tf_docs_output_method: inject
        tf_docs_git_push: 'true'
WARNING: If USAGE.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.

Renders

Example

Configuration

Inputs

Name Description Default Required
tf_docs_args Additional args to pass --sort-inputs-by-required --no-providers false
tf_docs_atlantis_file Generate directories by parsing an atlantis formatted yaml to enable provide the file name to parse (eg atlantis.yaml) (disabled by default) disabled false
tf_docs_content_type Generate document or table table false
tf_docs_find_dir Generate directories by running find ./tf_docs_find_dir -name *.tf (disabled by default) disabled false
tf_docs_git_commit_message Commit message terraform-docs: automated action false
tf_docs_git_push If true it will commit and push the changes false false
tf_docs_indention Indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) 2 false
tf_docs_output_file File in module directory where the docs should be placed USAGE.md false
tf_docs_output_method Method should be one of (replace/inject/print) where replace will replace the tf_docs_output_file, inject will inject the content between start and close delims and print will just print the output inject false
tf_docs_template When provided will be used as the template if/when the OUTPUT_FILE does not exist # Usage
<!--- BEGIN_TF_DOCS --->
<!--- END_TF_DOCS --->
 false
tf_docs_working_dir Directories of terraform modules to generate docs for seperated by commas (conflicts with atlantis/find dirs) . false

Outputs

Name Description
num_changed Number of files changed

Important Notes

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

Output Method (tf_docs_output_method)

print

This will just print the generated file

replace

This will create/replace the tf_docs_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: <!--- 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.

Auto commit changes

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

PR

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

Push

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

Content type (tf_docs_content_type)

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

Examples

Simple / Single folder

- name: Generate TF Docs
  uses: Dirrk/terraform-docs@v1.0.5
  with:
    tf_docs_working_dir: .
    tf_docs_output_file: README.md

Multi folder

- name: Generate TF Docs
  uses: Dirrk/terraform-docs@v1.0.5
  with:
    tf_docs_working_dir: .,example1,example3/modules/test
    tf_docs_output_file: README.md

Use atlantis.yaml v3 to find all dirs

- name: Generate TF docs
  uses: Dirrk/terraform-docs@v1.0.5
  with:
    tf_docs_atlantis_file: atlantis.yaml

Find all .tf file folders under a given directory

- name: Generate TF docs
  uses: Dirrk/terraform-docs@v1.0.5
  with:
    tf_docs_find_dir: examples/

Complete examples can be found here