From 4906d5ac2392b790ab79a26220185465f186dac0 Mon Sep 17 00:00:00 2001
From: Maxwell G <maxwell@gtmx.me>
Date: Tue, 17 Sep 2024 16:46:03 -0500
Subject: [PATCH] nox: add actionlint to lint Github Actions workflows (#1848)

(cherry picked from commit 3b43d6467dc97524a6e5184b069f4a590e9b4392)
---
 .github/workflows/reusable-nox.yml         |  2 +
 .github/workflows/reusable-pip-compile.yml |  2 +
 README.md                                  |  5 +++
 noxfile.py                                 | 47 ++++++++++++++++++++++
 4 files changed, 56 insertions(+)

diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml
index bf8ac66ab75..2f8b8a92900 100644
--- a/.github/workflows/reusable-nox.yml
+++ b/.github/workflows/reusable-nox.yml
@@ -23,6 +23,8 @@ jobs:
             python-versions: "3.11"
           - session: "checkers(docs-build)"
             python-versions: "3.11"
+          - session: "actionlint"
+            python-versions: "3.11"
     name: "Run nox ${{ matrix.session }} session"
     steps:
       - name: Check out repo
diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml
index 70c8c92414d..91e7ec3e59b 100644
--- a/.github/workflows/reusable-pip-compile.yml
+++ b/.github/workflows/reusable-pip-compile.yml
@@ -114,7 +114,9 @@ jobs:
         run: |
           set -x
           git diff || :
+          # shellcheck disable=SC2086
           git add ${changed_files}
+          # shellcheck disable=SC2086
           if git diff-index --quiet HEAD ${changed_files}; then
             echo "Nothing to do!"
             exit
diff --git a/README.md b/README.md
index e9392b53ba5..2966f6f51c6 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,11 @@ The `nox` configuration also contains session to run automated docs checkers.
   nox -s lint
   ```
 
+  The `actionlint` linter that is run as part of the `lint` session requires
+  `podman` or `docker` to be installed.
+  If both container engines are installed, `podman` is preferred.
+  Set `CONTAINER_ENGINE=docker` to change this behavior.
+
 ### Checking spelling
 
 Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
diff --git a/noxfile.py b/noxfile.py
index fd00278c42e..944c7ec4fd7 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -2,6 +2,7 @@
 
 import os
 import shlex
+import shutil
 from argparse import ArgumentParser, BooleanOptionalAction
 from glob import iglob
 from pathlib import Path
@@ -44,6 +45,29 @@ def install(session: nox.Session, *args, req: str, **kwargs):
     session.install("-r", f"tests/{req}.in", *args, **kwargs)
 
 
+CONTAINER_ENGINES = ("podman", "docker")
+CHOSEN_CONTAINER_ENGINE = os.environ.get("CONTAINER_ENGINE")
+ACTIONLINT_IMAGE = "docker.io/rhysd/actionlint"
+
+
+def _get_container_engine(session: nox.Session) -> str:
+    path: str | None = None
+    if CHOSEN_CONTAINER_ENGINE:
+        path = shutil.which(CHOSEN_CONTAINER_ENGINE)
+        if not path:
+            session.error(
+                f"CONTAINER_ENGINE {CHOSEN_CONTAINER_ENGINE!r} does not exist!"
+            )
+        return path
+    for engine in CONTAINER_ENGINES:
+        if path := shutil.which(engine):
+            return path
+    session.error(
+        f"None of the following container engines were found: {CONTAINER_ENGINES}."
+        f" {session.name} requires a container engine installed."
+    )
+
+
 @nox.session
 def static(session: nox.Session):
     """
@@ -92,12 +116,35 @@ def spelling(session: nox.Session):
     )
 
 
+@nox.session
+def actionlint(session: nox.Session) -> None:
+    """
+    Run actionlint to lint Github Actions workflows.
+    The actionlint tool is run in a Podman/Docker container.
+    """
+    engine = _get_container_engine(session)
+    session.run_always(engine, "pull", ACTIONLINT_IMAGE, external=True)
+    session.run(
+        engine,
+        "run",
+        "--rm",
+        # fmt: off
+        "--volume", f"{Path.cwd()}:/pwd:z",
+        "--workdir", "/pwd",
+        # fmt: on
+        ACTIONLINT_IMAGE,
+        *session.posargs,
+        external=True,
+    )
+
+
 @nox.session
 def lint(session: nox.Session):
     session.notify("typing")
     session.notify("static")
     session.notify("formatters")
     session.notify("spelling")
+    session.notify("actionlint")
 
 
 requirements_files = list(