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