docs(release): F-L11 closed as verified non-finding (no screenshot re… #11
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@v4 | |
| 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@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Install MkDocs Material | |
| # Pin major versions so a Material 10 release does not silently | |
| # break the build. We bump these as part of the quarterly | |
| # version-pinning audit (PUBLIC_RELEASE_PLAN.md §8 5.5). | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install \ | |
| 'mkdocs>=1.6,<2' \ | |
| 'mkdocs-material>=9.5,<10' \ | |
| 'pymdown-extensions>=10,<11' | |
| - 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@v4 | |
| 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 (not PRs). | |
| # 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.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@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Install MkDocs Material | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install \ | |
| 'mkdocs>=1.6,<2' \ | |
| 'mkdocs-material>=9.5,<10' \ | |
| 'pymdown-extensions>=10,<11' | |
| - 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@v5 | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site/ | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |