chore: Improved documentation for pre-commit

Author: actuarysailor

.pre-commit-hooks.yaml

@@ -184,54 +184,62 @@
   name: Terraform fmt (Docker)
   description: >-
     Rewrites all Terraform configuration files to a canonical format using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [terraform, fmt]
   files: \.(tf|tofu|tfvars|tftest\.hcl|tfmock\.hcl)$
   exclude: \.terraform/.*$
-  default: false
 
 - id: terraform_validate_docker
   name: Terraform validate (Docker)
-  description: Validates all Terraform configuration files using Docker.
+  description: >-
+    Validates all Terraform configuration files using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   require_serial: true
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [terraform, validate]
   pass_filenames: false
   files: \.(tf|tofu|tfvars|terraform\.lock\.hcl)$
   exclude: \.terraform/.*$
-  default: false
 
 - id: terraform_tflint_docker
   name: Terraform validate with tflint (Docker)
-  description: Validates all Terraform configuration files with TFLint using
-    Docker.
+  description: >-
+    Validates all Terraform configuration files with TFLint using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   require_serial: true
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [tflint, --chdir=.]
   pass_filenames: false
   files: \.(tf|tofu|tfvars)$
   exclude: \.terraform/.*$
-  default: false
 
 - id: terraform_docs_docker
   name: Terraform docs (Docker)
   description: >-
     Inserts input and output documentation into README.md using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   require_serial: true
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [terraform-docs, markdown, table, ., --output-file, README.md]
   pass_filenames: false
   files: \.(tf|tofu|terraform\.lock\.hcl)$
   exclude: \.terraform/.*$
-  default: false
 
 - id: terraform_checkov_docker
   name: Checkov (Docker)
-  description: Runs checkov on Terraform templates using Docker.
+  description: >-
+    Runs checkov on Terraform templates using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [checkov, -d, .]
@@ -240,30 +248,32 @@
   files: \.(tf|tofu)$
   exclude: \.terraform/.*$
   require_serial: true
-  default: false
 
 - id: terraform_trivy_docker
   name: Terraform validate with trivy (Docker)
   description: >-
     Static analysis of Terraform templates to spot potential security issues
     using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   require_serial: true
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [trivy, config, .]
   pass_filenames: false
   files: \.(tf|tofu|tfvars)$
   exclude: \.terraform/.*$
-  default: false
 
 - id: infracost_breakdown_docker
   name: Infracost breakdown (Docker)
-  description: Check terraform infrastructure cost using Docker.
+  description: >-
+    Check terraform infrastructure cost using Docker.
+    NOTE: Requires Docker to be available. Use 'skip' in .pre-commit-config.yaml
+    if running on pre-commit.ci or other environments without Docker.
   entry: ghcr.io/actuarysailor/pre-commit-terraform-tools:latest
   language: docker_image
   args: [infracost, breakdown, --path, .]
   pass_filenames: false
   require_serial: true
   files: \.(tf|tofu|tfvars|hcl)$
   exclude: \.terraform/.*$
-  default: false

README.md

@@ -94,7 +94,7 @@ TAG=latest
 docker pull ghcr.io/antonbabenko/pre-commit-terraform:$TAG
 ```
 
-All available tags [here](https://github.com/antonbabenko/pre-commit-terraform/pkgs/container/pre-commit-terraform/versions).
+All available tags are [available on GitHub Container Registry](https://github.com/antonbabenko/pre-commit-terraform/pkgs/container/pre-commit-terraform/versions).
 
 Check [About Docker image security](#about-docker-image-security) section to learn more about possible security issues and why you probably want to build and maintain your own image.
 
@@ -362,6 +362,22 @@ For users who prefer not to install tools locally, Docker-based versions are ava
 * Faster CI/CD execution (tools are pre-installed in the image)
 * Simplified dependency management
 
+**Requirements and limitations:**
+
+* Docker must be installed and accessible
+* For pre-commit.ci users: At this time, these hooks must be skipped as pre-commit.ci agents do not have Docker available.
+  * _Note: pre-commit has a Docker setup for hooks, so Docker support may be added in the future._
+* **You can still use Docker-based hooks in CI/CD pipelines** (such as GitHub Actions, GitLab CI, etc.) by running `pre-commit run --all-files` (or `pre-commit run -a`) on a self-hosted or GitHub-hosted runner where Docker is available. This allows you to enforce the same checks in CI as locally, even if pre-commit.ci does not support Docker yet.
+
+**Skipping Docker hooks on pre-commit.ci:**
+
+If you use pre-commit.ci, add this to your `.pre-commit-config.yaml`:
+
+```yaml
+ci:
+  skip: [terraform_fmt_docker, terraform_validate_docker, terraform_tflint_docker, terraform_docs_docker, terraform_checkov_docker, terraform_trivy_docker, infracost_breakdown_docker]
+```
+
 **Example usage:**
 
 ```yaml
@@ -410,8 +426,9 @@ You can specify environment variables that will be passed to the hook at runtime
 
 > [!IMPORTANT]
 > Variable values are exported _verbatim_:
-> - No interpolation or expansion are applied
-> - The enclosing double quotes are removed if they are provided
+>
+> * No interpolation or expansion are applied
+> * The enclosing double quotes are removed if they are provided
 
 Config example:
 
@@ -523,7 +540,7 @@ Note that `terraform_checkov` runs recursively during `-d .` usage. That means,
         - --args=--skip-check CKV2_AWS_8
     ```
 
-    Check all available arguments [here](https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html).
+    Check all available arguments in the [Checkov CLI Command Reference](https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html).
 
     For deprecated hook you need to specify each argument separately:
 

examples/.pre-commit-config-docker.yaml

@@ -1,6 +1,12 @@
 # Example .pre-commit-config.yaml for using Docker-based hooks
 # This configuration uses Docker containers instead of requiring local tool installation
 
+# Skip Docker hooks on pre-commit.ci (which doesn't support Docker)
+ci:
+  skip: [terraform_fmt_docker, terraform_validate_docker, terraform_tflint_docker,
+    terraform_docs_docker, terraform_checkov_docker, terraform_trivy_docker,
+    infracost_breakdown_docker]
+
 repos:
 - repo: https://github.com/actuarysailor/pre-commit-terraform
   rev: v1.96.1  # Use a stable release version