Autogenerating Terraform Documentation with terraform-docs and GitHub Actions

Writing a lot of Terraform modules and trying to maintain accurate and up-to-date Terraform documentation becomes increasingly challenging. This is where terraform-docs along with GitHub actions can assist you, they automate the generation of Terraform documentation.

In this blog post, I will show you how to use terraform-docs with GitHub Actions. This setup will automatically generate and update the Terraform documentation within the GitHub repository.

Why Automate Terraform Documentation?

Keeping a number of Terraform modules up to date can take time. Manually keeping the modules’ documentation up to date is another task. This process can be tedious and sometimes even neglected.

When working with any Terraform modules, I think it is essential to align the README file with the Terraform code. This includes updates. It is critical for collaboration and readability.

Automated documentation solves these problems by ensuring that:

1. Consistency: Your documentation always reflects the latest state of the Terraform code
2. Efficiency: Less time is spent manually updating README files
3. Collaboration: Can easily understand the purpose, inputs, outputs and usage of the Terraform modules
4. Reduced errors: Eliminates any risk of outdated or incorrect documentation

What is terraform-docs?

terraform-docs is a popular tool that generates documentation for Terraform modules based on their input variables, output values, providers, and resources. It creates a structured and readable format that can be injected directly into your README files or other documentation formats.

Setting Up GitHub Actions for terraform-docs

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 and push changes back to PR
      uses: terraform-docs/gh-actions@main
      with:
        working-dir: .
        output-file: README.md
        output-method: inject
        git-push: "true"

How it works

1. Trigger on Pull Requests: The workflow runs whenever a pull request is opened or updated.
2. Checkout Code: The actions/checkout@v3 step ensures the workflow operates on the latest code from the pull request branch.
3. Generate Documentation:
   • The terraform-docs/gh-actions@main action generates documentation based on the Terraform files in the specified directory (working-dir)
   • It updates the content into README.md (output-method: inject)
   • If there are changes to the README file, it pushes them back to the pull request branch (git-push: "true")

Example GitHub repository showing created documentation from the above

Whats the benefits to this?

No need to worry about manually updating README files with any Terraform changes, the automation will do that for you! Instead the focus is solely on updating the actual Terraform code

With having the Terraform documentation automated, it reduces risk of discrepancies between the Terraform code and its documentation

• Potential For Improved Collaboration

When a colleague wants to use the Terraform module, documentation is always up to date. Even during any new changes to the module during pull request phase – the documentation is up to date, allowing for a more straightforward review

Wrapping Up

Keeping Terraform module documentation up to date is certainly essential for forward maintainability and also collaboration. By using terraform-docs and GitHub Actions, it won’t feel like a chore to constantly remember to up date the documentation! Having it automated, ensures your documentation always reflects the latest state of the Terraform code

This approach saves time. It also improves team productivity. It achieves this by providing consistent and accurate module information during code reviews and development.

I do recommend to start automation your Terraform documentation, if you haven’t already 🙂 – it’s a small investment that will pay off immensely as your infrastructure grows!