Repository navigation
🐛 [v6] stage: a fork PR red only on a maintainer-run fork guard goes to the maintainer on its first red head, and its author is not nudged #17827
Workflow file for this run
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 Link Check | |
| # Why this exists | |
| # | |
| # kubestellar/docs (the org's published docs site, Next.js on Netlify at | |
| # kubestellar.io/docs/hive/*) pulls a growing subset of src/docs/*.md straight | |
| # from this repo's `v4` branch on every site build | |
| # (kubestellar/docs:scripts/sync-hive-docs.ts fetches the raw file over HTTP | |
| # and rewrites relative links to site routes or GitHub blob URLs). That sync | |
| # runs no Markdown linter and no link checker of its own — it trusts this | |
| # source tree to already be internally consistent. | |
| # | |
| # That trust broke concretely once already: #5206 fixed three cross-reference | |
| # anchors that a heading rename in design/tui.md had silently broken. Nothing | |
| # failed red when it happened; a human had to notice. This job is the gate | |
| # that catches the same class of break before merge, for every relative link | |
| # and heading anchor inside src/docs/ — whether or not the file happens to be | |
| # on the sync manifest today, since that manifest only grows over time. | |
| # | |
| # It intentionally does NOT validate http(s)/mailto links (network-dependent, | |
| # and not what broke in #5206) and does not touch the sync manifest itself, | |
| # which lives in the separate kubestellar/docs repository. | |
| # | |
| # The job also guards a second, differently-shaped surface: the wiki vault at | |
| # src/deploy/data/wiki/. src/Dockerfile bakes that tree into the image and | |
| # src/deploy/entrypoint.sh seeds it with `cp -rn /opt/hive/seed-data/* /data/`, | |
| # so it is served FLAT from /data/wiki/ with nothing above it. A parent- | |
| # relative link there resolves for a reviewer browsing this repo and 404s for | |
| # the operator reading the deployed page — the repo view is the one that lies, | |
| # which is what makes the break invisible in review (#5309). The wiki step | |
| # therefore runs --vault-root, which treats the vault directory as the reader's | |
| # whole filesystem and rejects any escape regardless of what exists in this | |
| # checkout. Outbound wiki references belong in absolute blob/v4 URLs, which | |
| # resolve identically in both views (#5308). | |
| on: | |
| push: | |
| branches: | |
| - v4 | |
| - v5 | |
| - v6 | |
| paths: | |
| - '*.md' | |
| - 'src/docs/**' | |
| - 'src/**' | |
| - 'src/deploy/data/wiki/**' | |
| - 'docs/**' | |
| - 'src/scripts/check-docs-links.py' | |
| - 'src/scripts/test-check-docs-links.sh' | |
| - 'src/scripts/check-docs-citations.py' | |
| - 'src/scripts/test-check-docs-citations.sh' | |
| - 'src/scripts/check-security-docs-readability.sh' | |
| - 'src/scripts/test-check-security-docs-readability.sh' | |
| - 'src/scripts/check-security-docs-rot.sh' | |
| - 'src/scripts/check-api-reference-citations.sh' | |
| - 'src/scripts/test-check-api-reference-citations.sh' | |
| - 'src/pkg/dashboard/**' | |
| - 'src/pkg/hub/**' | |
| - '.github/workflows/**' | |
| - 'bin/**' | |
| - '.github/workflows/docs-link-check.yml' | |
| pull_request: | |
| branches: | |
| - v4 | |
| - v5 | |
| - v6 | |
| paths: | |
| - '*.md' | |
| - 'src/docs/**' | |
| - 'src/**' | |
| - 'src/deploy/data/wiki/**' | |
| - 'docs/**' | |
| - 'src/scripts/check-docs-links.py' | |
| - 'src/scripts/test-check-docs-links.sh' | |
| - 'src/scripts/check-docs-citations.py' | |
| - 'src/scripts/test-check-docs-citations.sh' | |
| - 'src/scripts/check-security-docs-readability.sh' | |
| - 'src/scripts/test-check-security-docs-readability.sh' | |
| - 'src/scripts/check-security-docs-rot.sh' | |
| - 'src/scripts/check-api-reference-citations.sh' | |
| - 'src/scripts/test-check-api-reference-citations.sh' | |
| - 'src/pkg/dashboard/**' | |
| - 'src/pkg/hub/**' | |
| - '.github/workflows/**' | |
| - 'bin/**' | |
| - '.github/workflows/docs-link-check.yml' | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: ${{ github.event_name == 'pull_request' }} | |
| permissions: | |
| contents: read | |
| jobs: | |
| link-check: | |
| name: relative links and anchors resolve | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 15 | |
| steps: | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| - name: Self-test the checker against fixtures | |
| run: bash src/scripts/test-check-docs-links.sh | |
| - name: Check src/docs/ relative links and anchors | |
| run: python3 src/scripts/check-docs-links.py src/docs | |
| # Verifies every `pkg/<file>:<line>` citation in api-reference.md and | |
| # api-reference/*.md still | |
| # points at the route registration it names (hivecommons/hive#6628). | |
| - name: Self-test the api-reference citation checker | |
| run: bash src/scripts/test-check-api-reference-citations.sh | |
| - name: Check api-reference source citations | |
| run: bash src/scripts/check-api-reference-citations.sh | |
| # Verifies repo-local file:line citations across every src/docs/*.md file | |
| # still point at existing files and in-range lines (hivecommons/hive#7691). | |
| - name: Self-test the docs citation checker | |
| run: bash src/scripts/test-check-docs-citations.sh | |
| - name: Check src/docs file:line citations | |
| run: python3 src/scripts/check-docs-citations.py src/docs | |
| # Security docs must stay readable by a non-expert: Flesch-Kincaid grade | |
| # 11 or lower for SECURITY.md and the src/docs/security*/ioscan* set. | |
| - name: Self-test the security docs readability checker | |
| run: bash src/scripts/test-check-security-docs-readability.sh | |
| - name: Check security docs readability | |
| run: bash src/scripts/check-security-docs-readability.sh --verbose | |
| # Security docs must also stay current: a `Last reviewed:` date no | |
| # older than 120 days, and no "tracked in #N" sentence whose issue has | |
| # since closed. GITHUB_TOKEN lets the script ask GitHub for issue state. | |
| - name: Check security docs rot | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: bash src/scripts/check-security-docs-rot.sh | |
| # Repo-root docs/ was covered by nothing until #5491: it was absent from | |
| # both paths: filters and had no step, so a PR breaking a relative link | |
| # or heading anchor in any of its files ran no link check at all, and no | |
| # later PR caught it either. Same shape as #5309 (the wiki vault) and the | |
| # exemptions swept in #5388 — the guard was correct and simply never | |
| # aimed at this surface. | |
| # | |
| # Plain mode, NOT --vault-root: root docs/ is served from the repository, | |
| # so its many parent-relative links out to src/, bin/, .github/ and the | |
| # root README resolve normally for a reader. The vault's flat-layout | |
| # containment rule would reject exactly the links that are correct here. | |
| - name: Check repo-root docs/ relative links and anchors | |
| run: python3 src/scripts/check-docs-links.py docs | |
| # Repo-root markdown (CONTRIBUTING.md, README.md, ROADMAP.md, UPGRADE.md, | |
| # ...) was on no step until #7829: CONTRIBUTING.md shipped a link to a | |
| # docs/ path that never existed and nothing went red. --no-recurse keeps | |
| # this to the root's own files; every subtree that matters has its own | |
| # step above, and recursing from "." would also walk vendor/node_modules. | |
| - name: Check repo-root *.md relative links and anchors | |
| run: python3 src/scripts/check-docs-links.py . --no-recurse | |
| # The wiki vault is checked in --vault-root mode, which models the | |
| # DEPLOYED layout rather than this checkout. See the header comment and | |
| # check-docs-links.py's docstring: /data/wiki/ has nothing above it, so a | |
| # parent-relative link is rejected here even when the target exists in | |
| # the repo. Running the plain checker against this tree would pass | |
| # exactly the links that are broken in production (#5309). | |
| - name: Check wiki vault links against the deployed flat layout | |
| run: python3 src/scripts/check-docs-links.py src/deploy/data/wiki --vault-root |