docs: How to use pre-commit-terraform image to run pre-commit in CI

README.md

@@ -25,41 +25,43 @@ If you are using `pre-commit-terraform` already or want to support its developme
 
 ## Table of content
 
-* [Sponsors](#sponsors)
-* [Table of content](#table-of-content)
-* [How to install](#how-to-install)
-  * [1. Install dependencies](#1-install-dependencies)
-  * [2. Install the pre-commit hook globally](#2-install-the-pre-commit-hook-globally)
-  * [3. Add configs and hooks](#3-add-configs-and-hooks)
-  * [4. Run](#4-run)
-* [Available Hooks](#available-hooks)
-* [Hooks usage notes and examples](#hooks-usage-notes-and-examples)
-  * [Known limitations](#known-limitations)
-  * [All hooks: Usage of environment variables in `--args`](#all-hooks-usage-of-environment-variables-in---args)
-  * [All hooks: Set env vars inside hook at runtime](#all-hooks-set-env-vars-inside-hook-at-runtime)
-  * [All hooks: Disable color output](#all-hooks-disable-color-output)
-  * [All hooks: Log levels](#all-hooks-log-levels)
-  * [Many hooks: Parallelism](#many-hooks-parallelism)
-  * [checkov (deprecated) and terraform\_checkov](#checkov-deprecated-and-terraform_checkov)
-  * [infracost\_breakdown](#infracost_breakdown)
-  * [terraform\_docs](#terraform_docs)
-  * [terraform\_docs\_replace (deprecated)](#terraform_docs_replace-deprecated)
-  * [terraform\_fmt](#terraform_fmt)
-  * [terraform\_providers\_lock](#terraform_providers_lock)
-  * [terraform\_tflint](#terraform_tflint)
-  * [terraform\_tfsec (deprecated)](#terraform_tfsec-deprecated)
-  * [terraform\_trivy](#terraform_trivy)
-  * [terraform\_validate](#terraform_validate)
-  * [terraform\_wrapper\_module\_for\_each](#terraform_wrapper_module_for_each)
-  * [terrascan](#terrascan)
-  * [tfupdate](#tfupdate)
-  * [terragrunt\_providers\_lock](#terragrunt_providers_lock)
-* [Docker Usage](#docker-usage)
-  * [File Permissions](#file-permissions)
-  * [Download Terraform modules from private GitHub repositories](#download-terraform-modules-from-private-github-repositories)
-* [Authors](#authors)
-* [License](#license)
-  * [Additional information for users from Russia and Belarus](#additional-information-for-users-from-russia-and-belarus)
+* [Collection of git hooks for Terraform to be used with pre-commit framework](#collection-of-git-hooks-for-terraform-to-be-used-with-pre-commit-framework)
+  * [Sponsors](#sponsors)
+  * [Table of content](#table-of-content)
+  * [How to install](#how-to-install)
+    * [1. Install dependencies](#1-install-dependencies)
+    * [2. Install the pre-commit hook globally](#2-install-the-pre-commit-hook-globally)
+    * [3. Add configs and hooks](#3-add-configs-and-hooks)
+    * [4. Run](#4-run)
+  * [Available Hooks](#available-hooks)
+  * [Hooks usage notes and examples](#hooks-usage-notes-and-examples)
+    * [Known limitations](#known-limitations)
+    * [All hooks: Usage of environment variables in `--args`](#all-hooks-usage-of-environment-variables-in---args)
+    * [All hooks: Set env vars inside hook at runtime](#all-hooks-set-env-vars-inside-hook-at-runtime)
+    * [All hooks: Disable color output](#all-hooks-disable-color-output)
+    * [All hooks: Log levels](#all-hooks-log-levels)
+    * [Many hooks: Parallelism](#many-hooks-parallelism)
+    * [checkov (deprecated) and terraform\_checkov](#checkov-deprecated-and-terraform_checkov)
+    * [infracost\_breakdown](#infracost_breakdown)
+    * [terraform\_docs](#terraform_docs)
+    * [terraform\_docs\_replace (deprecated)](#terraform_docs_replace-deprecated)
+    * [terraform\_fmt](#terraform_fmt)
+    * [terraform\_providers\_lock](#terraform_providers_lock)
+    * [terraform\_tflint](#terraform_tflint)
+    * [terraform\_tfsec (deprecated)](#terraform_tfsec-deprecated)
+    * [terraform\_trivy](#terraform_trivy)
+    * [terraform\_validate](#terraform_validate)
+    * [terraform\_wrapper\_module\_for\_each](#terraform_wrapper_module_for_each)
+    * [terrascan](#terrascan)
+    * [tfupdate](#tfupdate)
+    * [terragrunt\_providers\_lock](#terragrunt_providers_lock)
+  * [Docker Usage](#docker-usage)
+    * [File Permissions](#file-permissions)
+    * [Download Terraform modules from private GitHub repositories](#download-terraform-modules-from-private-github-repositories)
+  * [Github Actions](#github-actions)
+  * [Authors](#authors)
+  * [License](#license)
+    * [Additional information for users from Russia and Belarus](#additional-information-for-users-from-russia-and-belarus)
 
 ## How to install
 
@@ -1167,6 +1169,62 @@ Finally, you can execute `docker run` with an additional volume mount so that th
 docker run --rm -e "USERID=$(id -u):$(id -g)" -v ~/.netrc:/root/.netrc -v $(pwd):/lint -w /lint ghcr.io/antonbabenko/pre-commit-terraform:latest run -a
 ```
 
+## Github Actions
+
+You can use this hook in your GitHub Actions workflow togehther with [pre-commit](https://pre-commit.com). To easy up dependency management, you can use the managed [docker image](#docker-usage) within your workflow. Make sure to set the image tag to the version you want to use.
+
+In this repository's pre-commit [workflow file](.github/workflows/pre-commit.yml) we run pre-commit without the container image.
+
+Here is an example that use the container image, includes caching of pre-commit dependencies and uses the `pre-commit` command to run the checks (but fixes will be not automatically push back to your branch, when it possible):
+
+```yaml
+name: pre-commit-terraform
+
+on:
+  pull_request:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/antonbabenko/pre-commit-terraform:latest # latest used here for simplicity, not recommended
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - run: |
+          git config --global --add safe.directory $GITHUB_WORKSPACE
+          git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/*
+
+      - name: Get changed files
+        id: file_changes
+        run: |
+          export DIFF=$(git diff --name-only origin/${{ github.base_ref }} ${{ github.sha }})
+          echo "Diff between ${{ github.base_ref }} and ${{ github.sha }}"
+          echo "files=$( echo "$DIFF" | xargs echo )" >> $GITHUB_OUTPUT
+
+      - name: fix tar dependency in alpine container image
+        run: |
+          apk --no-cache add tar
+          # check python modules installed versions
+          python -m pip freeze --local
+
+      - name: Cache pre-commit since we use pre-commit from container
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-3|${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Execute pre-commit
+        run: |
+          pre-commit run --color=always --show-diff-on-failure --files ${{ steps.file_changes.outputs.files }}
+```
+
 ## Authors
 
 This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from these awesome contributors: