Merge pull request #798 from stackhpc/add-pre-commit-hooks

feat: add pre-commit hooks

Author: markgoddard

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/sirwart/ripsecrets
+    rev: v0.1.7
+    hooks:
+      - id: ripsecrets

doc/source/contributor/index.rst

@@ -11,3 +11,4 @@ This guide is for contributors of the StackHPC Kayobe configuration project.
    release-notes
    environments/index
    package-updates
+   pre-commit

doc/source/contributor/pre-commit.rst

@@ -0,0 +1,47 @@
+================
+Pre-commit Hooks
+================
+
+StackHPC Kayobe configuration carries support for
+`pre-commit hooks <https://pre-commit.com/>`_ which simplify the use of git
+hooks enabling the identification and repairing of broken or poor code
+before committing.
+These hooks are designed to make working within SKC easier and less error prone.
+
+Currently the following hooks are provided:
+
+- ``check-yaml``: perform basic yaml syntax linting
+- ``end-of-file-fixer``: identify and automatically fix missing newline
+- ``trailing-whitespace``: identify and automatically fix excessive white space
+- ``ripsecrets``: identify and prevent secrets from being committed to the branch
+
+.. warning::
+   The hook ``ripsecrets`` is capable of preventing the accidental leaking of secrets
+   such as those found within `secrets.yml` or `passwords.yml`.
+   However if the secret is contained within a file on it's own and lacks a certain level
+   of entropy then the secret will not be identified as such as and maybe leaked as a result.
+
+Installation of `pre-commit` hooks is handled via the `install-pre-commit-hooks` playbook
+found within the Ansible directory.
+Either run the playbook manually or add the playbook as a hook within Kayobe config such as
+within `control-host-bootstrap/post.d`.
+Once done you should find `pre-commit` is available within the `kayobe` virtualenv.
+
+To run the playbook using the following command
+
+- ``kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/install-pre-commit-hooks.yml``
+
+Whereas to run the playbook when control host bootstrap runs ensure it registered as symlink using the following command
+
+- ``mkdir -p ${KAYOBE_CONFIG_PATH}/hooks/control-host-bootstrap/post.d``
+- ``ln -s ${KAYOBE_CONFIG_PATH}/ansible/install-pre-commit-hooks.yml ${KAYOBE_CONFIG_PATH}/hooks/control-host-bootstrap/post.d/install-pre-commit-hooks.yml``
+
+All that remains is the installation of the hooks themselves which can be accomplished either by
+running `pre-commit run` or using `git commit` when you have changes that need to be committed.
+This will trigger a brief installation process of the hooks which may take a few minutes.
+This a one time process and will not be required again unless new hooks are added or existing ones are updated.
+
+.. note::
+   Currently if you run ``pre-commit run --all-files`` it will make a series of changes to
+   release notes that lack new lines as well configuration files that ``check-yaml`` does not
+   approve of.

etc/kayobe/ansible/install-pre-commit-hooks.yml

@@ -0,0 +1,21 @@
+---
+- name: Install pre-commit hooks
+  hosts: localhost
+  gather_facts: false
+  vars:
+    pre_commit_version: 3.5.0
+  tasks:
+    - name: Install pre-commit hooks
+      block:
+        - name: Install pre-commit hooks into kayobe virtual env
+          ansible.builtin.pip:
+            name: pre-commit
+            version: "{{ pre_commit_version  }}"
+            virtualenv: "{{ lookup('ansible.builtin.env', 'VIRTUAL_ENV') | default(omit, true) }}"
+          register: pip_install
+
+        - name: Register pre-commit hooks with git
+          ansible.builtin.command:
+            cmd: "{{ lookup('ansible.builtin.env', 'VIRTUAL_ENV') | default(lookup('ansible.builtin.env', 'HOME') ~ '/.local', true) }}/bin/pre-commit install"
+          args:
+            chdir: "{{ playbook_dir | dirname | dirname | dirname }}"

releasenotes/notes/add-pre-commit-hooks-07ce3b82bbe1d7a3.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    Add playbook to install pre-commit hooks and register them with git.
+    The hooks currently configured to be installed will check yaml syntax,
+    fix new line at end of file and remove excess whitespace. This is
+    currently opt-in which can be achieved by running `install-pre-commit-hooks`
+    playbook.