ci: harden GitHub Actions workflows

.github/workflows/codeql.yml

@@ -20,14 +20,20 @@ on:
   schedule:
     - cron: '29 12 * * 1'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
 jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
     permissions:
-      actions: read
+      actions: read # Read workflow metadata required by CodeQL.
       contents: read
-      security-events: write
+      security-events: write # Upload CodeQL analysis results.
 
     strategy:
       fail-fast: false
@@ -40,11 +46,13 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        persist-credentials: false
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4
+      uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -58,7 +66,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v4
+      uses: github/codeql-action/autobuild@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -71,6 +79,6 @@ jobs:
     #   ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4
+      uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/dependency-review.yml

@@ -7,14 +7,21 @@
 name: 'Dependency Review'
 on: [pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
 jobs:
   dependency-review:
+    name: Dependency review
     runs-on: ubuntu-latest
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@v5.0.0
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

.github/workflows/mypy.yml

@@ -2,17 +2,26 @@ name: Type Checking
 
 on: [push, pull_request, workflow_dispatch]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   mypy:
     # uncomment the line before to disable this job if needed.
     # if: false
     name: mypy
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.0.1
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"

.github/workflows/prek.yml

@@ -1,9 +1,19 @@
 name: Prek checks
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   prek:
+    name: Prek
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: j178/prek-action@v3.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0

.github/workflows/ruff.yml

@@ -2,12 +2,22 @@ name: Linting
 
 on: [push, pull_request, workflow_dispatch]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   ruff:
+    name: Ruff
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/ruff-action@v4.1.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/ruff-action@278981a28ce3188b1e39527901f38254bf3aac89 # v4.1.0
         with:
           args: " check --output-format=concise"
       - run: ruff format --check

.github/workflows/tests.yml

@@ -7,8 +7,16 @@ on:
     branches: ["main", "develop"]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   test:
+    name: Python tests
     runs-on: ubuntu-latest
     env:
       SKIP_COVERAGE_UPLOAD: false
@@ -23,7 +31,7 @@ jobs:
 
     services:
       postgres:
-        image: postgres:18
+        image: postgres:18.6@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
@@ -35,27 +43,33 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.0.1
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
 
       - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+        run: uv python install "$PYTHON_VERSION"
 
       - name: Run tests
         # For example, using `pytest`
-        run: uv run --all-extras -p ${{ matrix.python-version }} pytest tests
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+        run: uv run --all-extras -p "$PYTHON_VERSION" pytest tests
           --cov-report=xml
 
       - name: Run codacy-coverage-reporter
         env:
           CODACY_CONFIGURED: ${{ secrets.CODACY_PROJECT_TOKEN }}
         if: ${{ env.CODACY_CONFIGURED != ''}}
-        uses: codacy/codacy-coverage-reporter-action@v1
+        uses: codacy/codacy-coverage-reporter-action@89d6c85cfafaec52c72b6c5e8b2878d33104c699 # v1.3.0
         continue-on-error: true
         with:
           project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}

.github/workflows/zizmor.yml

@@ -0,0 +1,36 @@
+name: GitHub Actions Security
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main", "develop"]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  zizmor:
+    name: Zizmor
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Run Zizmor
+        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2
+        with:
+          version: 1.29.0 # Keep in sync with the pyproject.toml dev dependency.
+          collect: workflows,actions
+          persona: pedantic
+          online-audits: true
+          advanced-security: false
+          annotations: true

CONTRIBUTING.md

@@ -192,11 +192,14 @@ As before, this will generate updated `requirements.txt` and
     regularly to ensure the dependency files are updated and that the linters all
     pass.
 
-#### GitHub CI Action
+#### GitHub CI checks
 
 The checks in this pre-commit hook are also automatically run for each commit
 pushed to GitHub and for Pull Requests. This is controlled by the
-`~/.github/workflows/prek.yml` configuration file.
+`.github/workflows/prek.yml` configuration file. GitHub Actions also runs the
+test suite, type checking, and security checks. See the
+[Continuous Integration](https://fastapi-template.seapagan.net/development/ci/)
+guide for the corresponding local commands and Zizmor configuration.
 
 ## Testing
 

docs/development/ci.md

@@ -0,0 +1,80 @@
+# Continuous Integration
+
+GitHub Actions checks every pull request and changes pushed to the main
+development branches. These checks cover code quality, typing, tests,
+dependencies, and the security of the GitHub Actions configuration itself.
+
+## Run CI Checks Locally
+
+Run the relevant checks before opening or updating a pull request:
+
+```console
+$ poe ruff
+$ poe mypy
+$ poe test
+$ poe pre
+$ poe zizmor
+```
+
+`poe pre` runs the repository's configured pre-commit hooks against all files.
+The other tasks are useful as narrower checks while developing. Some hosted
+checks, including CodeQL and dependency review, have no direct local
+equivalent.
+
+## Audit GitHub Actions with Zizmor
+
+[Zizmor](https://docs.zizmor.sh/){:target="_blank"} audits GitHub Actions
+workflows and action definitions for security issues. Zizmor is pinned as a
+development dependency so that local and hosted audits use the same version. It
+is installed by either `uv sync` or `pip install -r requirements-dev.txt`; no
+separate tool installation is required.
+
+Run the repository's configured audit with:
+
+```console
+$ poe zizmor
+```
+
+The task scans workflow and action definitions using Zizmor's `pedantic`
+persona. The dedicated GitHub Actions workflow applies the same policy and runs
+online audits.
+
+### Enable Online Audits Locally
+
+The Zizmor command-line tool runs offline unless a GitHub API token is
+available. Set any one of these equivalent environment variables to enable
+online audits:
+
+| Variable | Typical use |
+| --- | --- |
+| `ZIZMOR_GITHUB_TOKEN` | Tool-specific token; recommended for local use |
+| `GH_TOKEN` | Token shared with the GitHub CLI |
+| `GITHUB_TOKEN` | General GitHub automation token |
+
+For example, reuse the token managed by the authenticated GitHub CLI session:
+
+```console
+$ export ZIZMOR_GITHUB_TOKEN="$(gh auth token)"
+$ poe zizmor
+```
+
+The token only needs read access to repository contents. Keep it out of the
+repository and application `.env` files.
+
+Set `ZIZMOR_OFFLINE=1` to force offline mode even when a token is available.
+Set `ZIZMOR_NO_ONLINE_AUDITS=1` to allow remote inputs to be fetched while
+skipping audits that require GitHub API access.
+
+The hosted workflow does not require a separately configured repository secret.
+The Zizmor action uses the job's automatically provided GitHub token and the
+workflow grants only `contents: read` permission.
+
+### Personas and Suppressed Findings
+
+The `pedantic` persona is the repository's local and hosted CI policy. Zizmor's
+`auditor` persona includes additional review-oriented findings that require
+manual assessment and may not be appropriate as routine CI failures.
+
+Consequently, a successful pedantic run can report suppressed findings. This
+means those findings belong to a different persona; it does not mean they were
+disabled with inline comments or configuration.

mkdocs.yml

@@ -86,6 +86,7 @@ nav:
       - Metadata: customization/meta.md
       - Templates: customization/templates.md
   - Development and Testing:
+      - Continuous Integration: development/ci.md
       - With a Local Server: development/local.md
       - With Docker: development/docker.md
       - Documentation: development/documentation.md

pyproject.toml

@@ -63,7 +63,7 @@ dev = [
   "poethepoet>=0.48.0",
   "pyfakefs>=6.2.0",
   "pymarkdownlnt>=0.9.39",
-    "pytest==9.1.1",
+  "pytest==9.1.1",
   "pytest-asyncio>=1.4.0",
   "pytest-clarity>=1.0.1",
   "pytest-cov>=7.1.0",
@@ -91,6 +91,7 @@ dev = [
   "types-redis>=4.6.0.20241004",
   "pytest-xdist>=3.8.0",
   "types-markdown>=3.10.2.20260712",
+  "zizmor==1.29.0", # Keep in sync with .github/workflows/zizmor.yml.
 ]
 
 [tool.uv.sources]
@@ -120,6 +121,12 @@ test.cmd = "pytest"
 "test:skipped".cmd = "pytest --quiet --collect-only -m skip --no-cov"
 "test:skipped".help = "Show skipped tests without running all tests"
 
+# zizmor task to check github actions
+# currently the deafult invocation fails d/t our prek config. We ignore the prek
+# config check for now until the fixed version is released.
+zizmor.help = "Check all GitHub actions using 'zizmor'"
+zizmor.cmd = "zizmor --persona=pedantic --collect=workflows,actions ."
+
 # Add 'ty' type checker - this is still beta software and has false positives
 # compared to 'mypy', but suspect it will exentually replace it.
 ty.help = "Run the 'ty' type-checker (Alpha pre-release version)"

requirements-dev.txt

@@ -173,3 +173,4 @@ websockets==15.0
 win32-setctime==1.2.0 ; sys_platform == 'win32'
 wrapt==1.17.2
 wtforms==3.1.2
+zizmor==1.29.0