chore(audit): Q3 2026 Splunk version-pinning audit #76
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs | |
| # Phase 2.8 deliverable (added 2026-05-18 — PUBLIC_RELEASE_PLAN.md §5 | |
| # row 2.8). Builds the MkDocs Material site on every PR and every push | |
| # to main; deploys to GitHub Pages only when the repository is public | |
| # (Phase 3.4 flips it public — until then, the deploy job is skipped | |
| # and the build job is what gates docs PRs). | |
| # | |
| # Why split into two jobs: | |
| # - `build` — always runs. Catches broken markdown, broken links, | |
| # missing nav entries, etc. Runs with `--strict` so any | |
| # warning fails the build. | |
| # - `deploy` — only runs on push-to-main AND the repo is public. | |
| # GitHub Pages on private repos requires Pro/Team/ | |
| # Enterprise; on a free private repo the deploy step | |
| # would fail with a 404 on the Pages API. Guard mirrors | |
| # codeql.yml + scorecard.yml. | |
| # | |
| # Local validation: | |
| # pip install mkdocs-material | |
| # mkdocs serve # http://127.0.0.1:8000 | |
| # mkdocs build --strict # exits non-zero on any warning | |
| on: | |
| pull_request: | |
| branches: [main] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - '.github/workflows/docs.yml' | |
| push: | |
| branches: [main] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - '.github/workflows/docs.yml' | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| concurrency: | |
| # Allow the latest commit on main to cancel an in-flight deploy | |
| # while preserving each PR's own build queue. | |
| group: docs-${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build: | |
| name: Build docs site | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 | |
| with: | |
| # Fetch full history so future `git-revision-date-localized` | |
| # plugin support (if we add it) can read commit dates. | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6 | |
| with: | |
| python-version: '3.11' | |
| - name: Install MkDocs Material | |
| # Pin via requirements/docs.txt (hashed lockfile) so a | |
| # Material 10 release does not silently break the build AND | |
| # no swap-by-version-mirror attack can substitute a different | |
| # wheel. We bump the .in file + regenerate the .txt as part | |
| # of the quarterly version-pinning audit | |
| # (PUBLIC_RELEASE_PLAN.md §8 5.5). | |
| # No `pip install --upgrade pip` — pip self-upgrade can't be | |
| # hash-pinned; see ci.yml for the rationale. | |
| run: pip install --require-hashes -r requirements/docs.txt | |
| - name: Build site | |
| # Initial deploy uses `--verbose` only so legacy relative links | |
| # in migrated docs (e.g. ../README.md) don't block the first | |
| # green build. A follow-up will flip to `--strict` once those | |
| # links are audited and either rewritten to absolute GitHub | |
| # URLs or replaced with anchors inside the site. | |
| # PUBLIC_RELEASE_PLAN.md §10 "v1.1" carries the strict-mode | |
| # flip as a follow-up. | |
| run: mkdocs build --verbose | |
| - name: Upload site artifact | |
| # Always upload — even on build failure we want the partial | |
| # site for debugging (mkdocs writes what it has). | |
| if: always() | |
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 | |
| with: | |
| name: site-${{ github.sha }} | |
| path: site/ | |
| retention-days: 14 | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| needs: build | |
| runs-on: ubuntu-latest | |
| # Gate 1: only on push-to-main OR manual workflow_dispatch (not PRs). | |
| # Adding workflow_dispatch as of 2026-05-23: until then, manually | |
| # re-triggering this workflow (e.g. after enabling Pages or fixing | |
| # a settings issue) silently skipped the deploy job because the | |
| # gate was push-only, leaving the maintainer wondering why the | |
| # site stayed 404 even though the run was "successful". | |
| # Gate 2: only when the repo is public. GitHub Pages on a private | |
| # repo requires Pro/Team/Enterprise; on free, the deploy API | |
| # returns 404 and the job would fail. Phase 3.4 (PUBLIC_RELEASE_PLAN.md) | |
| # flips the repo public — until then, this job is skipped and the | |
| # `build` job above is what gates docs work. | |
| if: >- | |
| (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && | |
| github.ref == 'refs/heads/main' && | |
| github.event.repository.private == false | |
| permissions: | |
| # Required for the actions/deploy-pages action to publish. | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6 | |
| with: | |
| python-version: '3.11' | |
| - name: Install MkDocs Material | |
| # Same lockfile as the build job — see requirements/docs.txt. | |
| # Both jobs MUST stay synchronized; regenerating one updates | |
| # both via the shared requirements file. | |
| # No `pip install --upgrade pip` — pip self-upgrade can't be | |
| # hash-pinned; see ci.yml for the rationale. | |
| run: pip install --require-hashes -r requirements/docs.txt | |
| - name: Build site | |
| # Same posture as the build job — verbose without strict for v1 | |
| # (see comment on the build job for the strict-mode plan). | |
| run: mkdocs build --verbose | |
| - name: Configure Pages | |
| uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6 | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 | |
| with: | |
| path: site/ | |
| # upload-pages-artifact v4.0.0 introduced a "hidden files are | |
| # excluded by default" change. MkDocs Material writes | |
| # `.nojekyll` to `site/` so GitHub Pages skips Jekyll | |
| # processing — without that file, GitHub Pages would 404 on | |
| # mkdocs-emitted paths starting with `_` (assets/_static | |
| # paths, etc.). Setting include-hidden-files: true preserves | |
| # v3 behavior and ensures the deploy is correct when Phase | |
| # 3.4 flips the repo public and this step actually fires. | |
| include-hidden-files: true | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5 |