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

.github/workflows/pre-commit.yaml

@@ -54,3 +54,44 @@ jobs:
         SKIP: check-added-large-files,check-merge-conflict,check-vcs-permalinks,forbid-new-submodules,no-commit-to-branch,end-of-file-fixer,trailing-whitespace,check-yaml,check-merge-conflict,check-executables-have-shebangs,check-case-conflict,mixed-line-ending,detect-aws-credentials,detect-private-key,shfmt,shellcheck
       with:
         extra_args: --color=always --show-diff-on-failure --files ${{ steps.file_changes.outputs.files }}
+
+  pre-commit-container:
+    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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - 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
+
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - 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 }}

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
 
@@ -102,7 +104,7 @@ All available tags [here](https://github.com/antonbabenko/pre-commit-terraform/p
 **Build from scratch**:
 
 > [!IMPORTANT]
-> To build image you need to have [`docker buildx`](https://docs.docker.com/build/install-buildx/) enabled as default builder.  
+> To build image you need to have [`docker buildx`](https://docs.docker.com/build/install-buildx/) enabled as default builder.
 > Otherwise - provide `TARGETOS` and `TARGETARCH` as additional `--build-arg`'s to `docker build`.
 
 When hooks-related `--build-arg`s are not specified, only the latest version of `pre-commit` and `terraform` will be installed.
@@ -207,7 +209,7 @@ Otherwise, you can follow [this gist](https://gist.github.com/etiennejeanneaurev
 
 Ensure your PATH environment variable looks for `bash.exe` in `C:\Program Files\Git\bin` (the one present in `C:\Windows\System32\bash.exe` does not work with `pre-commit.exe`)
 
-For `checkov`, you may need to also set your `PYTHONPATH` environment variable with the path to your Python modules.  
+For `checkov`, you may need to also set your `PYTHONPATH` environment variable with the path to your Python modules.
 E.g. `C:\Users\USERNAME\AppData\Local\Programs\Python\Python39\Lib\site-packages`
 
 </details>
@@ -360,10 +362,10 @@ Less verbose log levels will be implemented in [#562](https://github.com/antonba
 
 ### Many hooks: Parallelism
 
-> All, except deprecated hooks: `checkov`, `terraform_docs_replace` and hooks which can't be paralleled this way: `infracost_breakdown`, `terraform_wrapper_module_for_each`.  
+> All, except deprecated hooks: `checkov`, `terraform_docs_replace` and hooks which can't be paralleled this way: `infracost_breakdown`, `terraform_wrapper_module_for_each`.
 > Also, there's a chance that parallelism have no effect on `terragrunt_fmt` and `terragrunt_validate` hooks
 
-By default, parallelism is set to `number of logical CPUs - 1`.  
+By default, parallelism is set to `number of logical CPUs - 1`.
 If you'd like to disable parallelism, set it to `1`
 
 ```yaml
@@ -419,7 +421,7 @@ args:
   - --hook-config=--parallelism-ci-cpu-cores=N
 ```
 
-If you don't see code above in your `pre-commit-config.yaml` or logs - you don't need it.  
+If you don't see code above in your `pre-commit-config.yaml` or logs - you don't need it.
 `--parallelism-ci-cpu-cores` used only in edge cases and is ignored in other situations. Check out its usage in [hooks/_common.sh](hooks/_common.sh)
 
 ### checkov (deprecated) and terraform_checkov
@@ -567,7 +569,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files
     * create a documentation file
     * extend existing documentation file by appending markers to the end of the file (see item 1 above)
     * use different filename for the documentation (default is `README.md`)
-    * use the same insertion markers as `terraform-docs` by default. It will be default in `v2.0`.  
+    * use the same insertion markers as `terraform-docs` by default. It will be default in `v2.0`.
       To migrate to `terraform-docs` insertion markers, run in repo root:
 
       ```bash
@@ -592,7 +594,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files
         - --args=--config=.terraform-docs.yml
     ```
 
-    > **Warning**  
+    > **Warning**
     > Avoid use `recursive.enabled: true` in config file, that can cause unexpected behavior.
 
 5. If you need some exotic settings, it can be done too. I.e. this one generates HCL files:
@@ -743,7 +745,7 @@ To replicate functionality in `terraform_docs` hook:
 
 3. `terraform_providers_lock` support passing custom arguments to its `terraform init`:
 
-    > **Warning**  
+    > **Warning**
     > DEPRECATION NOTICE: This is available only in `no-mode` mode, which will be removed in v2.0. Please provide this keys to [`terraform_validate`](#terraform_validate) hook, which, to take effect, should be called before `terraform_providers_lock`
 
     ```yaml
@@ -924,10 +926,10 @@ To replicate functionality in `terraform_docs` hook:
         - --hook-config=--retry-once-with-cleanup=true     # Boolean. true or false
     ```
 
-    > **Important**  
+    > **Important**
     > The flag requires additional dependency to be installed: `jq`.
 
-    > **Note**  
+    > **Note**
     > Reinit can be very slow and require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.
 
     When `--retry-once-with-cleanup=true`, in each failed directory the cached modules and providers from the `.terraform` directory will be deleted, before retrying once more. To avoid unnecessary deletion of this directory, the cleanup and retry will only happen if Terraform produces any of the following error messages:
@@ -938,7 +940,7 @@ To replicate functionality in `terraform_docs` hook:
     * "Module not installed"
     * "Could not load plugin"
 
-    > **Warning**  
+    > **Warning**
     > When using `--retry-once-with-cleanup=true`, problematic `.terraform/modules/` and `.terraform/providers/` directories will be recursively deleted without prompting for consent. Other files and directories will not be affected, such as the `.terraform/environment` file.
 
     **Option 2**
@@ -957,7 +959,7 @@ To replicate functionality in `terraform_docs` hook:
 
    `terraform_validate` hook will try to reinitialize them before running the `terraform validate` command.
 
-    > **Caution**  
+    > **Caution**
     > If you use Terraform workspaces, DO NOT use this option ([details](https://github.com/antonbabenko/pre-commit-terraform/issues/203#issuecomment-918791847)). Consider the first option, or wait for [`force-init`](https://github.com/antonbabenko/pre-commit-terraform/issues/224) option implementation.
 
 1. `terraform_validate` in a repo with Terraform module, written using Terraform 0.15+ and which uses provider `configuration_aliases` ([Provider Aliases Within Modules](https://www.terraform.io/language/modules/develop/providers#provider-aliases-within-modules)), errors out.
@@ -1009,7 +1011,7 @@ To replicate functionality in `terraform_docs` hook:
    [...]
    ```
 
-    > **Tip**  
+    > **Tip**
     > The latter method will leave an "aliased-providers.tf.json" file in your repo. You will either want to automate a way to clean this up or add it to your `.gitignore` or both.
 
 ### terraform_wrapper_module_for_each
@@ -1033,8 +1035,8 @@ Sample configuration:
     - --args=--verbose        # Verbose output
 ```
 
-**If you use hook inside Docker:**  
-The `terraform_wrapper_module_for_each` hook attempts to determine the module's short name to be inserted into the generated `README.md` files for the `source` URLs. Since the container uses a bind mount at a static location, it can cause this short name to be incorrect.  
+**If you use hook inside Docker:**
+The `terraform_wrapper_module_for_each` hook attempts to determine the module's short name to be inserted into the generated `README.md` files for the `source` URLs. Since the container uses a bind mount at a static location, it can cause this short name to be incorrect.
 If the generated name is incorrect, set them by providing the `module-repo-shortname` option to the hook:
 
 ```yaml
@@ -1084,7 +1086,7 @@ If the generated name is incorrect, set them by providing the `module-repo-short
         - --args=--version 2.5.0 # Will be pined to specified version
     ```
 
-Check [`tfupdate` usage instructions](https://github.com/minamijoyo/tfupdate#usage) for other available options and usage examples.  
+Check [`tfupdate` usage instructions](https://github.com/minamijoyo/tfupdate#usage) for other available options and usage examples.
 No need to pass `--recursive .` as it is added automatically.
 
 ### terragrunt_providers_lock
@@ -1167,6 +1169,46 @@ 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 also check the container image with pre-commit.
+Here is another more simple example which includes caching of pre-commit dependencies and uses the `pre-commit` command to run the checks.
+
+```yaml
+name: pre-commit-terraform
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/antonbabenko/pre-commit-terraform:v1.88.4 # make sure to use the correct version
+    steps:
+    - uses: actions/checkout@v4
+    - name: fixes and dependencys
+      shell: bash
+      run: |
+        # fix permissions in the container
+        git config --global --add safe.directory $GITHUB_WORKSPACE
+        apk --no-cache add tar
+        # check python modules installed versions
+        python -m pip freeze --local
+    - uses: actions/cache@v4
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit-3|${{ hashFiles('.pre-commit-config.yaml') }}
+    - shell: bash
+      run: |
+        pre-commit run --show-diff-on-failure --color=always -a || cat $HOME/.cache/pre-commit/pre-commit.log
+
+```
+
 ## Authors
 
 This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from these awesome contributors: