[BUG] pre-commit documentation incorrect

[mjpieters]

Describe the bug The documentation tells you to download the .pre-commit-hooks.yaml file; from https://docs.kubelinter.io/#/using-kubelinter?id=using-kubelinter-with-the-pre-commit-framework:

Download the .pre-commit-hooks.yaml file in the Git repository in which you want to install the KubeLinter pre-commit hooks:

curl -O https://raw.githubusercontent.com/stackrox/kube-linter/main/.pre-commit-hooks.yaml

This is not how pre-commit usually works, nor is the above necessary at all. You specify the repository in your local .pre-commit-config.yaml file, instead.

Expected behavior The documentation should be corrected to follow the canonical instructions on adding plugins with a GitHub repository.

You add a section to your .pre-commit-config.yaml file referencing the kube-linter repository, plus a specific release, plus the files that should trigger the hook when changed. E.g. to run the current release of kube-linter on all changed yaml files in a repository, use:

  - repo: https://github.com/stackrox/kube-linter
    rev: 0.2.4
    hooks:
      - id: kube-linter
        args: [lint]

The hook configuration already sets types, but you could use a files: regex pattern to limit the hook to a specific directory containing your resources or chart.

A local configuration file can be configured using additional entries in the args list, e.g. args: [lint, --config, kubelinter-config.yaml]

Additional context Rather than require that users must always set args: [lint], consider giving your hooks configuration an entry that includes lint:

- id: kube-linter
  name: KubeLinter
  description: This hook installs (using Go) and runs the KubeLinter utility to lint Helm charts and Kubernetes YAML files.
  entry: kube-linter
  language: golang
  types: [yaml]
  entry: kube-linter lint

This does assume that the linter is generally used without specifying the specific resource.

Also, please consider adding Helm chart versions of the hooks, with pass_filenames: false; the hook would need to be given the path to Chart.yaml in args, but would run whenever any of the files in the chart changed:

- id: kube-linter-helm
  name: KubeLinter (Helm)
  description: This hook installs (using Go) and runs the KubeLinter utility to lint Helm charts. Requires that `args` names the chart(s) to lint when the hook matches.
  entry: kube-linter lint
  language: golang
  pass_filenames: false
  types: [yaml]


- id: kube-linter-helm-system
  name: KubeLinter (Helm) System
  description: This hook runs the KubeLinter utility that exists already on the system to lint Helm charts. Requires that `args` names the chart(s) to lint when the hook matches.
  entry: kube-linter lint
  language: system
  pass_filenames: false
  types: [yaml]


- id: kube-linter-docker
  name: KubeLinter (Helm) Docker
  description: This hook runs kube-linter using the project's official docker image
  language: docker_image
  entry: stackrox/kube-linter:latest /kube-linter lint
  pass_filenames: false
  types: [yaml]

[viswajithiii]

Hey @mjpieters, thanks so much for filing this thoughtful, detailed issue. Makes a lot of sense. The other maintainers and I don't use pre-commit, and this was a community contribution, so this feedback is very valuable.

Would you be open to sending a PR with this? Both the docs changes and the additional hooks seem fine to me. No worries if not, one of the maintainers will get to this in that case. cc: @gaurav-nelson, who handles our docs generally.

[mjpieters]

I probably can create a PR here, yes.

I've verified that you can override a hook entry in your local repository commit hooks configuration, so I'll update all entries to make kube-linter lint the default command. There is also no need to create separate helm versions, you just have to add pass_filenames: false in your local configuration. So, all I do for the .pre-commit-hooks.yaml definition is update the entry lines to add lint to each entry. I can't imagine why you'd ever want to run, say, kube-linter checks list or kube-linter version as a pre-commit hook, after all.

For the documentation, then, I'll explain how to configure a hook for linting either kubernetes YAML files or Helm charts.

[viswajithiii]

Sounds like a plan!

[gaurav-nelson]

Thanks @mjpieters for a detailed explanation. I'll keep an eye out for your PR. 🙇🏼‍♂️

[hassenius]

@mjpieters I haven't really used pre-commit before, and was looking to experiment with it for the first time with kube-linter. So this PR would come in really handy for me too if comes in within the next week or so when I'm hoping to circle back to it... ;)

[djhoese]

@mjpieters Does this new version of the hooks exist in a pull request somewhere?

[mjpieters]

@mjpieters Does this new version of the hooks exist in a pull request somewhere?

Sorry, this one fell by the wayside and I'm not sure I have time at the moment. 😞