feat: add git pre-commit hook integration

.github/workflows/poetry_update.yml → .github/workflows/auto_updates.yml

@@ -1,5 +1,6 @@
 # This is a workflow for updating Python dependencies with Poetry.
 # Major version updates are handled separately, by Dependabot.
+# It will also update the pre-commit hooks to use latest tags.
 ---
 name: Update Deps
 
@@ -10,8 +11,8 @@ on:
     - cron: '35 14 * * 1'
 
 jobs:
-  poetry-update:
-    name: Update Python dependencies
+  workflow-auto-updates:
+    name: Update dependencies and hooks
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -24,8 +25,19 @@ jobs:
       - name: Checkout the repo
         uses: actions/checkout@v3
 
-      - name: Install poetry
-        run: pipx install poetry
+      # This GPG key is for the `phylum-bot` account and used in order to ensure commits are signed/verified
+      - name: Import GPG key for bot account
+        uses: crazy-max/ghaction-import-gpg@v5
+        with:
+          gpg_private_key: ${{ secrets.PHYLUM_BOT_GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.PHYLUM_BOT_GPG_PASSPHRASE }}
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+
+      - name: Install poetry and pre-commit
+        run: |
+          pipx install poetry
+          pipx install pre-commit
 
       - name: Configure poetry
         run: poetry config virtualenvs.in-project true
@@ -45,17 +57,20 @@ jobs:
           poetry env use python${{ matrix.python-version }}
           poetry install --verbose --no-root
 
-      - name: Poetry update
+      - name: Update Python dependencies
         run: poetry update -vv
 
+      - name: Update pre-commit hooks
+        run: pre-commit autoupdate --freeze
+
       - name: Commit changes
         id: commit
         continue-on-error: true
+        # NOTE: The git user name and email used for commits is already configured,
+        #       by the crazy-max/ghaction-import-gpg action.
         run: |
-          git config user.name 'Phylum Bot'
-          git config user.email '[email protected]'
-          git commit -a -m "build: Bump poetry.lock dependencies"
-          git push --force origin HEAD:auto-poetry-update
+          git commit -a -m "build: Bump poetry.lock dependencies and pre-commit hooks"
+          git push --force origin HEAD:workflow-auto-updates
 
       - name: Create Pull Request
         if: ${{ steps.commit.outcome == 'success' }}
@@ -66,8 +81,8 @@ jobs:
             github.rest.pulls.create({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              head: "auto-poetry-update",
+              head: "workflow-auto-updates",
               base: context.ref,
-              title: "build: Bump poetry.lock dependencies",
-              body: "Bump dependencies in poetry.lock for all SemVer-compatible updates.",
+              title: "build: Bump poetry.lock dependencies and pre-commit hooks",
+              body: "Bump dependencies in `poetry.lock` and hooks in `.pre-commit-config.yaml`.",
             });

.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+# This is the config for using `pre-commit` on this repository.
+#
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+#
+# NOTE: Individual hook revisions are kept up to date automatically with
+#       the `auto_updates` workflow, which bumps hooks to the latest tag.
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3298ddab3c13dd77d6ce1fc0baf97691430d84b0  # frozen: v4.3.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: f6c139c5215ce04fd3e73a900f1372942d58eca0  # frozen: 22.6.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: a78007c1e9de96e71d5fb3e720c2b9fae8ed8abf  # frozen: v2.37.3
+    hooks:
+      - id: pyupgrade
+        args: [--py37-plus]
+
+  # NOTE: don't use this config for your own repositories. Instead, see
+  #       "Git pre-commit Integration" in `docs/sync/git_precommit.md`
+  - repo: local
+    hooks:
+      - id: phylum-ci
+        name: analyze lockfile with phylum-ci
+        language: system
+        files: ^poetry\.lock$
+        entry: poetry run phylum-ci

.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+# This is the config for defining `pre-commit` hooks for use in other repositories.
+#
+# See https://pre-commit.com for more information
+---
+- id: phylum
+  name: analyze lockfile with phylum
+  description: Run `phylum` on a dependency lockfile
+  entry: phylum-ci
+  language: python
+  require_serial: true
+  stages: [commit]

CONTRIBUTING.md

@@ -87,7 +87,20 @@ Here's how to set up `phylum-ci` for local development.
     git clone [email protected]:phylum-dev/phylum-ci.git
     ```
 
-2. Ensure all supported Python versions are installed locally
+2. Optional: Install [pre-commit](https://pre-commit.com/) and the local hooks
+
+    ```sh
+    # If the `pre-commit` tool is not already installed, the recommended method is to use pipx
+    pipx install pre-commit
+
+    # Installing with homebrew is another good option
+    brew install pre-commit
+
+    # Use the `pre-commit` tool to install the git hooks used by the repository
+    pre-commit install
+    ```
+
+3. Ensure all supported Python versions are installed locally
    1. The strategy is to support all released minor versions of Python that are not end-of-life yet
    2. The current list
       1. at the time of this writing is 3.7, 3.8, 3.9, and 3.10
@@ -108,59 +121,64 @@ Here's how to set up `phylum-ci` for local development.
     pyenv global 3.10.x 3.9.x 3.8.x 3.7.x
     ```
 
-3. Ensure [poetry](https://python-poetry.org/docs/) is installed
-4. Install dependencies with `poetry`, which will automatically create a virtual environment:
+4. Ensure [poetry](https://python-poetry.org/docs/) is installed
+5. Install dependencies with `poetry`, which will automatically create a virtual environment:
 
     ```sh
     cd phylum-ci
     poetry install
     ```
 
-5. Create a branch for local development:
+6. Create a branch for local development:
 
     ```sh
     git checkout -b <name-of-your-branch>
     ```
 
     Now you can make your changes locally.
 
-6. If new dependencies are added, do so in a way that does not add upper version constraints and ensure
+7. If new dependencies are added, do so in a way that does not add upper version constraints and ensure
    the `poetry.lock` file is updated (and committed):
 
     ```sh
     # Unless there is a reason to do so, prefer to add dependencies without constraints
-    poetry add new-dependency-name
+    poetry add "new-dependency-name==*"
 
-    # When a version constraint is not specified, poetry chooses one. For example (in pyproject.toml):
+    # When a version constraint is not specified, poetry chooses one. For example, the command:
+    #
+    #   $ poetry add new-dependency-name
+    #
+    # results in a caret-style version constraint added to the dependency in pyproject.toml:
     #
     #   new-dependency-name = "^1.2.3"
     #
-    # Unless the constraint was intentional, change the entry to remove the constraint:
+    # Unless the constraint was intentional, change the pyproject.toml entry to remove the constraint:
     #
     #   new-dependency-name = "*"
 
     # Update the lockfile and the local environment to get the latest versions of dependencies
     poetry update
 
-    # Dependencies will be checked automatically in CI during a PR, but checking locally is possible:
+    # Dependencies will be checked automatically in CI during a PR. They will also be checked
+    # with the local pre-commit hook, if enabled. Manually checking locally is also possible:
     phylum analyze poetry.lock
     ```
 
-7. When you're done making changes, check that your changes pass the tests:
+8. When you're done making changes, check that your changes pass the tests:
 
     ```sh
     poetry run tox
     ```
 
-8. Commit your changes and push your branch to GitHub:
+9. Commit your changes and push your branch to GitHub:
 
     ```sh
     git add .
     git commit -m "Description of the changes goes here"
     git push --set-upstream origin <name-of-your-branch>
     ```
 
-9. Submit a pull request (PR) through the GitHub website
+10. Submit a pull request (PR) through the GitHub website
 
 ## Pull Request Guidelines
 

README.md

@@ -7,6 +7,7 @@
 ![GitHub last commit](https://img.shields.io/github/last-commit/phylum-dev/phylum-ci)
 [![GitHub Workflow Status (branch)][workflow_shield]][workflow_test]
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)][CoC]
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)][pre-commit]
 
 Utilities for integrating Phylum into CI pipelines (and beyond)
 
@@ -15,6 +16,7 @@ Utilities for integrating Phylum into CI pipelines (and beyond)
 [workflow_shield]: https://img.shields.io/github/workflow/status/phylum-dev/phylum-ci/Test/main?label=Test&logo=GitHub
 [workflow_test]: https://github.com/phylum-dev/phylum-ci/actions/workflows/test.yml
 [CoC]: https://github.com/phylum-dev/phylum-ci/blob/main/CODE_OF_CONDUCT.md
+[pre-commit]: https://github.com/pre-commit/pre-commit
 [contributing]: https://github.com/phylum-dev/phylum-ci/blob/main/CONTRIBUTING.md
 [changelog]: https://github.com/phylum-dev/phylum-ci/blob/main/CHANGELOG.md
 [security]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/security.md
@@ -116,14 +118,18 @@ The current CI platforms/environments supported are:
 * GitHub Actions
   * See the [GitHub Actions Integration documentation][github_docs] for more info
 
+* Git `pre-commit` Hooks
+  * See the [Git `pre-commit` Integration documentation][precommit_docs] for more info
+
 * None (local use)
   * This is the "fall-through" case used when no other environment is detected
   * Can be useful to analyze lockfiles locally, prior to or after submitting a pull/merge request (PR/MR) to a CI system
     * Establishing a successful submission prior to submitting a PR/MR to a CI system
     * Troubleshooting after submitting a PR/MR to a CI system and getting unexpected results
 
-[gitlab_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/gitlab_ci.md
-[github_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/github_actions.md
+[gitlab_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/gitlab_ci.md
+[github_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/github_actions.md
+[precommit_docs]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/sync/git_precommit.md
 
 ## License