terraform-docs GitHub Actions

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 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.0.0 (uses terraform-docs v0.16.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/[email protected]
      with:
        working-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

Configuration

Inputs

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: <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->. 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

Examples

Single folder

- name: Generate TF Docs
  uses: terraform-docs/[email protected]
  with:
    working-dir: .

Multi folder

- name: Generate TF Docs
  uses: terraform-docs/[email protected]
  with:
    working-dir: .,example1,example3/modules/test

Use atlantis.yaml v3 to find all directories

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

Find all .tf file under a given directory

- name: Generate TF docs
  uses: terraform-docs/[email protected]
  with:
    find-dir: examples/

Recursively under a given directory

- name: Generate TF docs
  uses: terraform-docs/[email protected]
  with:
    working-dir: examples/
    recursive: true
    recursive-path: modules

Complete examples can be found here.