MAINT - CI improvements (security and maintenance)

.github/actions/set-dev-env/action.yml

@@ -1,3 +1,5 @@
+# Reusable action to set our PST development environment
+# DO NOT use for release jobs since we cache dependencies
 name: Setup PST CI environment
 description: Create a PST dev environment
 

.github/workflows/CI.yml

@@ -1,3 +1,4 @@
+# Testing (pytest, a11y-tests), profiling, and coverage checks for PST
 name: continuous-integration
 
 # Concurrency group that uses the workflow name and PR number if available
@@ -21,6 +22,9 @@ on:
     branches:
       - main
   pull_request:
+    branches:
+      - "*"
+  # allows this to be used as a composite action in other workflows
   workflow_call:
   # allow manual triggering of the workflow, while debugging
   workflow_dispatch:
@@ -31,10 +35,12 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
+        # https://github.com/actions/runner-images
         # macos-14==latest
-        # ubuntu-20.04==latest
-        os: ["ubuntu-latest", "ubuntu-24.04", "macos-14", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        # ubuntu-24.04==latest
+        # windows-2022==latest
+        os: ["ubuntu-latest", "ubuntu-22.04", "macos-14", "windows-latest"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
@@ -59,11 +65,15 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
       - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
         with:
           python-version: ${{ matrix.python-version }}
           pandoc: true
+
       - name: "Run tests ✅"
         shell: bash
         run: |
@@ -77,6 +87,7 @@ jobs:
           else
             python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
+
       - name: "Upload coverage data to GH artifacts 📤"
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
         uses: actions/upload-artifact@v4
@@ -93,101 +104,42 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
       - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
           pandoc: true
           graphviz: true
+
       - name: "Run accessibility tests with playwright 🎭"
         # build PST, build docs, then run a11y-tests
         run: python -Im tox run -m a11y
 
-  # Build our docs (PST) on major OSes and check for warnings
-  build-site:
-    name: "build PST docs"
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.12"]
-        include:
-          # oldest Python version with the oldest Sphinx version
-          - os: ubuntu-latest
-            python-version: "3.9"
-            sphinx-version: "6.1"
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: "Checkout repository 🛎"
-        uses: actions/checkout@v4
-      - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
-        with:
-          python-version: ${{ matrix.python-version }}
-          pandoc: true
-          graphviz: true
-      - name: "Build docs and check for warnings 📖"
-        shell: bash
-        run: |
-          # check if there is a specific Sphinx version to build with
-          # example substitution: tox run -e py39-sphinx61-docs
-          if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
-          # build with the default Sphinx version
-          # example substitution: tox run -e py312-docs
-          else
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs
-          fi
-
-  # Run Lighthouse audits on the built site (kitchen-sink only)
-  lighthouse-audit:
-    needs: build-site
-    runs-on: ubuntu-latest
-    env:
-      DOCS_DIR: "audit"
-    steps:
-      - name: "Checkout repository 🛎"
-        uses: actions/checkout@v4
-      - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
-        with:
-          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
-      - name: "Copy kitchen sink to a tiny site"
-        run: |
-          mkdir -p ${{ env.DOCS_DIR }}/site
-          cp -r docs/examples/kitchen-sink ${{ env.DOCS_DIR }}/site/kitchen-sink
-          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > ${{ env.DOCS_DIR }}/site/index.rst
-          echo 'html_theme = "pydata_sphinx_theme"' > ${{ env.DOCS_DIR }}/site/conf.py
-          echo '.. toctree::\n   :glob:\n\n   *' >> ${{ env.DOCS_DIR }}/site/index.rst
-
-          # build docs without checking for warnings
-          python -Im tox run -e docs-no-checks
-
-      - name: "Audit with Lighthouse 🔦"
-        uses: treosh/lighthouse-ci-action@v12
-        with:
-          configPath: ".github/workflows/lighthouserc.json"
-          temporaryPublicStorage: true
-          uploadArtifacts: true
-          runs: 3 # Multiple runs to reduce variance
-
   coverage:
     name: "Check coverage"
     needs: run-pytest
     runs-on: ubuntu-latest
-    # avoid running this on schedule, releases, or workflow_call
-    if: github.event_name != 'schedule' && github.event_name != 'release' && github.event_name != 'workflow_call'
+    # avoid running this on schedule, releases, workflow_call, or workflow_dispatch
+    if: github.event_name != 'schedule' && github.event_name != 'release' && github.event_name != 'workflow_call' && github.event_name != 'workflow_dispatch'
     permissions:
       contents: write
       pull-requests: write
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
       - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+
       - run: python -Im pip install --upgrade coverage[toml]
+
       - name: "Download coverage data 📥"
         uses: actions/download-artifact@v4
         with:
@@ -229,23 +181,38 @@ jobs:
           path: python-coverage-comment-action.txt
 
   profiling:
-    needs: [build-site, run-pytest]
+    needs: [run-pytest]
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
       - name: "Setup CI environment 🛠"
-        uses: ./.github/actions/set-dev-env
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
         with:
           # 3.12 is not supported by py-spy yet
           python-version: "3.11"
+
       - name: "Run profiling with py-spy 🕵️‍♂️"
         # profiling needs to be run as sudo
         run: python -m tox run -e py311-profile-docs -- -o docbuild_profile.svg
         continue-on-error: true
+
       - name: "Upload profiling data to GH artifacts 📤"
         uses: actions/upload-artifact@v4
         with:
           name: profile-results
           path: docbuild_profile.svg
           if-no-files-found: ignore
+
+  # Calling the coverage-comment action from the main CI workflow
+  # we might want to pin the SHA once merged
+  coverage-comment:
+    uses: ./.github/workflows/coverage.yml
+    needs: [coverage]
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: read

.github/workflows/coverage.yml

@@ -1,14 +1,11 @@
 name: Post coverage comment
 
 on:
-  workflow_run:
-    workflows: ["continuous-integration"]
-    types:
-      - completed
+  workflow_call:
 
 jobs:
   test:
-    name: "Run tests & display coverage"
+    name: "Display code coverage"
     runs-on: ubuntu-latest
     if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
     permissions:
@@ -20,9 +17,11 @@ jobs:
         id: get-run
         uses: octokit/[email protected]
         with:
-          route: GET /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}
+          route: GET /repos/"${REPO}"/actions/runs/"${WORKFLOW_RUN_ID}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }}
 
       # this needs the .coverage file so we download from the CI workflow artifacts
       - name: "Download coverage data 📥"

.github/workflows/docs.yml

@@ -0,0 +1,131 @@
+# This workflow is checks that the documentation can be built across multiple OSes, Python, and Sphinx versions.
+# It also checks for broken links in the documentation and runs Lighthouse audits on the built site.
+
+name: docs-checks
+
+# Concurrency group that uses the workflow name and PR number if available
+# or commit SHA as a fallback. If a new build is triggered under that
+# concurrency group while a previous build is running it will be canceled.
+# Repeated pushes to a PR will cancel all previous builds, while multiple
+# merges to main will not cancel.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1" # Make tools pretty
+  DEFAULT_PYTHON_VERSION: "3.12" # keep in sync with tox.ini
+  PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "*"
+  # allows this to be used as a composite action in other workflows
+  workflow_call:
+  # allow manual triggering of the workflow, while debugging
+  workflow_dispatch:
+
+jobs:
+  # Build our docs (PST) on major OSes and check for warnings
+  build-site:
+    name: "build PST docs"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+        include:
+          # oldest Python version with the oldest Sphinx version
+          - os: ubuntu-latest
+            python-version: "3.9"
+            sphinx-version: "6.1"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: "Setup CI environment 🛠"
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
+        with:
+          python-version: ${{ matrix.python-version }}
+          pandoc: true
+          graphviz: true
+
+      - name: "Build docs and check for warnings 📖"
+        shell: bash
+        run: |
+          # check if there is a specific Sphinx version to build with
+          # example substitution: tox run -e py39-sphinx61-docs
+          if [ -n "${{matrix.sphinx-version}}" ]; then
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
+          # build with the default Sphinx version
+          # example substitution: tox run -e py312-docs
+          else
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs
+          fi
+
+  # Run Lighthouse audits on the built site (kitchen-sink only)
+  lighthouse-audit:
+    needs: build-site
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: "Setup CI environment 🛠"
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+
+      - name: "Copy kitchen sink to a tiny site"
+        run: |
+          # ensuring proper scaping of the variable
+          docs_dir="${DOCS_DIR}"
+          mkdir -p $docs_dir/site
+          cp -r docs/examples/kitchen-sink $docs_dir/site/kitchen-sink
+          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > $docs_dir/site/index.rst
+          echo 'html_theme = "pydata_sphinx_theme"' > $docs_dir/site/conf.py
+          echo '.. toctree::\n   :glob:\n\n   *' >> $docs_dir/site/index.rst
+
+          # build docs without checking for warnings
+          python -Im tox run -e docs-no-checks
+        env:
+          DOCS_DIR: "audit"
+
+      - name: "Audit with Lighthouse 🔦"
+        uses: treosh/lighthouse-ci-action@v12
+        with:
+          configPath: ".github/workflows/lighthouserc.json"
+          temporaryPublicStorage: true
+          uploadArtifacts: true
+          runs: 3 # Multiple runs to reduce variance
+
+  # Check for broken links in our docs
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: "Setup CI environment 🛠"
+        uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1
+
+      - name: "Check for broken links 🔗"
+        run: python -Im tox -e docs-linkcheck
+
+      - name: "Upload file with broken links 📤"
+        uses: actions/upload-artifact@v4
+        with:
+          name: broken-links
+          path: docs/_build/linkcheck/output.txt
+        if: ${{ always() }}