How I use pre-commit for Terraform

How I use pre-commit for Terraform

Manually running CLI commands to check your code before committing can be repetitive, slow, and drain your time. You may even forget to run these, resulting in Pull Request checks failing. I know I have.

In this post, I will cover how I use the pre-commit tool to run checks locally when I try committing my Terraform code. Yes, pre-commit can use in a broad range of scenarios, but I will be covering how to use it with Terraform.

What is pre-commit

pre-commit operates as a git hook, commits triggering a set of tools to check your code. You can set what tools to use to scan your local repository using a configuration file. If a tool finds any errors, for example a misconfiguration of a coding language, it will stop the commit from happening. This is a shift left approach that will improve security and best practices in coding.

Installing pre-commit


Using brew, install pre-commit using the following command:

brew install pre-commit


With PIP, install pre-commit using the following command:

pip install pre-commit

The hooks I use

Let's look at the hooks I use when working with Terraform:

terraform_docs - This tool auto-generates readme files containing information on modules, providers and resources that gives users an easy-to-read and central page that can be digested faster than reading the code.

terraform fmt - Terraform format will structure your config files so it presents cleanly.

terraform validate - Terraform validate will check to ensure the configuration is correct based on HCL.

tflint - TFLint will check for errors and encourage best practices.

tfsec - TFSec reviews the config files for any security concerns based on best practices and reports to the user how to change them to resolve the error.

Installing these tools before proceeding

As the pre-commit will run locally, you must ensure you have these installed. Terraform fmt and validate are part of Terraform, so make sure to have this installed. If you follow the links above for the other tools, you will find instructions on installing these.

Create a pre-commit config file

Below is a copy of my config file:

  - repo:
    rev: "v0.16.0"
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "", "./"]
  - repo:
    rev: "v1.74.1"
      - id: terraform_fmt
      - id: terraform_tflint
      - id: terraform_validate
      - id: terraform_tfsec

This file is stored locally on my device, ready for me to copy and paste to any new repos so I can enable pre-commit.

The file must be named .pre-commit-config.yaml in a repo. Name it differently if storing outside of the repo, but it needs to have that defined name when you copy and paste it to a repo.

Enable pre-commit on the repo

When you have a config file created, follow the below steps:

  1. Checkout your remote repo for local use
  2. Copy the pre-commit-config.yaml file to the root of the checked-out repo
  3. In a terminal, run the following command in the root of the checked-out repo:
    pre-commit install
  4. Once you run the command, any changes you commit from now will trigger all hooks

What if I need to skip hooks on commit

You might hit a scenario where you do not want to trigger hooks when you commit. In that case, you do not need to uninstall pre-commit or amend the configuration file. Instead run the following:

git commit --no-verify -m "your commit message"

Yes it's that simple, the --no-verify will prevent the hooks being triggered, allowing you to commit.

Did you find this article valuable?

Support James Cook by becoming a sponsor. Any amount is appreciated!