VyOS readthedocs (mirror of https://github.com/vyos/vyos-documentation.git) https://git.amelek.net/vyos/vyos-documentation.git/atom?h=feature%2FT9082-codeql-onboard 2026-07-10T16:01:35+00:00 2026-07-10T16:01:35+00:00 Yuriy Andamasov yuriy@vyos.io 2026-07-10T16:01:35+00:00 urn:sha1:b78ccb662b2359a2cb5f60c4040c30004b43a412 🤖 Generated by [robots](https://vyos.io) 2026-07-10T14:14:13+00:00 Yuriy Andamasov yuriy@vyos.io 2026-07-10T14:14:13+00:00 urn:sha1:21689ef59b0eb34b1a29eda739dc10d33d25b44a * docs-infra: scaffold Cloudflare workers workspace (versions.json v2, matrix, toolchain) 🤖 Generated by [robots](https://vyos.io) * docs-infra: record full Phase-0 plan decision in workers/PLAN.md 🤖 Generated by [robots](https://vyos.io) * docs-infra: shared content worker — asset serving, cache classes, X-Docs-Build, canary no-store 🤖 Generated by [robots](https://vyos.io) * docs-infra: run worker script before assets; test fetch entrypoint 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex manifest loader + dispatch map + runtime binding guard (TDD) 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex redirects (aliases, PDF, trailing-slash) + special paths (TDD) 🤖 Generated by [robots](https://vyos.io) * docs-infra: PDF redirect honors pdf:null and preserves query 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex UA gate — allowlist-wins, log-only AI crawlers, empty block list at launch 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex router (pipeline §3.2), themed 404/503, /kb seam, env configs + congruence test 🤖 Generated by [robots](https://vyos.io) * docs-infra: add missing-User-Agent regression test for apex UA gate 🤖 Generated by [robots](https://vyos.io) * docs-infra: R2-streaming preview worker — MIME map, noindex, no-store (TDD) 🤖 Generated by [robots](https://vyos.io) * docs-infra: preview 404 no-store + fetch handler tests 🤖 Generated by [robots](https://vyos.io) * docs-infra: bootstrap script — binding-target workers must exist before apex deploys 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex run_worker_first, lockfile for npm ci, PDF Location from manifest 🤖 Generated by [robots](https://vyos.io) * docs-infra: derive html_baseurl from DOCS_VERSION_SLUG with RTD fallback (canonical gate prereq) 🤖 Generated by [robots](https://vyos.io) * docs-infra: version picker + status banner + language scaffold (vanilla JS, TDD pure core) 🤖 Generated by [robots](https://vyos.io) * docs-infra: picker preserves query+hash across switch; valid breadcrumb markup 🤖 Generated by [robots](https://vyos.io) * docs-infra: Pagefind search wrapper with runtime base-path + preview prefix handling (TDD) 🤖 Generated by [robots](https://vyos.io) * docs-infra: pagefind wrapper — asset-failure notice + UI stylesheet load 🤖 Generated by [robots](https://vyos.io) * docs-infra: gate Pagefind searchbox to CF builds (RTD keeps stock search until cutover) 🤖 Generated by [robots](https://vyos.io) * docs-infra: deploy sanity gates — limits, critical pages, count-delta, canonical (TDD) 🤖 Generated by [robots](https://vyos.io) * docs-infra: hermetic gate tests via fixture versions.json 🤖 Generated by [robots](https://vyos.io) * docs-infra: docs-build workflow — candidate/smoke/promote two-stage deploy + registry + rollback Two-stage CF Workers pipeline: build in pinned container, assemble artifact, sanity gates, deploy candidate, scoped pre-traffic smoke via canary apex, promote (rollback-id capture, hostname purge, registry upload), post-promote probe + auto-rollback. DOCS_CF_LIVE repo variable gates every docs.vyos.io production interaction pre-cutover. scripts/docs_gates/smoke.py adds one authorized check beyond the spec: the version's index.html probe asserts the #vyos-search mount div is present in the response body, guarding CI silently forgetting DOCS_VERSION_SLUG (which would otherwise ship stock RTD search without the Pagefind gate noticing). 🤖 Generated by [robots](https://vyos.io) * docs-infra: build docs image in-workflow with buildx cache (v4.1 — digest pin dropped) Plan v4.1 amendment: the ghcr.io digest-pinned image does not exist (workflow would hard-fail at the first docker step on every push). Replace the BUILD_IMAGE env placeholder with an in-workflow docker build from docker/Dockerfile via docker/setup-buildx-action@v3 + docker/build-push-action@v6 (context: docker/, load: true, tags: docs-build:local, GHA cache from/to). The checked-out commit is the pin; buildx GHA cache keeps repeat builds cheap. Sphinx-build step swaps to docs-build:local; inner script unchanged. 🤖 Generated by [robots](https://vyos.io) * docs-infra: apex/preview deploy workflow — canary auto, production behind environment approval * docs-infra: apex-deploy concurrency guard (per-ref, cancel-in-progress) 🤖 Generated by [robots](https://vyos.io) * docs-infra: fork-safe PR preview pipeline — approval record, R2 prefixes, label consumption, cleanup * docs-infra: nightly preview sweep — pipefail + per-prefix failure isolation 🤖 Generated by [robots](https://vyos.io) * docs-infra: nightly canary QA — per-entry sweep + URL-parity corpus vs RTD 🤖 Generated by [robots](https://vyos.io) * docs-infra: parity sweep scoped to CF-built versions; transport-error resilience 🤖 Generated by [robots](https://vyos.io) * docs-infra: one-off bootstrap workflow (binding targets — runs once on this push) 🤖 Generated by [robots](https://vyos.io) * docs-infra: remove one-off bootstrap workflow (bootstrap complete) 🤖 Generated by [robots](https://vyos.io) * docs-infra: one-off canary apex + preview deploy (route targets for Task 3.6 step 2c) 🤖 Generated by [robots](https://vyos.io) * docs-infra: remove one-off canary deploy workflow (targets live) 🤖 Generated by [robots](https://vyos.io) * docs-infra: address Phase-0 CodeRabbit findings (canonical gate, error caching, registry pointer, validation) 🤖 Generated by [robots](https://vyos.io) * docs-infra: strengthen manifest tests (full dispatch iteration, mutation-free validate) 🤖 Generated by [robots](https://vyos.io) * docs-infra: address GitHub CodeRabbit review (pointer-after-probe, fail-closed sweeps, block-precedence UA gate, preview hardening) 🤖 Generated by [robots](https://vyos.io) * docs-infra: adversarial review fixes — error no-store, probe retry, PR-list membership, preview dotted-segment 🤖 Generated by [robots](https://vyos.io) * docs-infra: serve oversized legacy PDF from R2 via apex (spec §5 fallback) The 1.3 PDF (29.2 MiB) exceeds the 25 MiB static-asset cap and is absent from the legacy content Worker's build, so /_/downloads/en/1.3/pdf/ (and the picker's PDF link) 301'd into a dead-end 404 post-cutover. Add the R2 object fallback spec §5 already documented but never implemented: a DOCS_PDFS R2 bucket binding on the apex Worker, a manifest pdf_r2_key field (1.3 only), and a router step ahead of version dispatch that streams the object with its own cache class (canary/error still force no-store). 🤖 Generated by [robots](https://vyos.io) * docs-infra: PDF R2 fallback honors Range + If-None-Match, preserves ETag 🤖 Generated by [robots](https://vyos.io) 2026-05-11T11:20:07+00:00 Quill Cronwall quilljazz@gmail.com 2026-05-11T11:12:50+00:00 urn:sha1:ec6f33f3c256e839b443bb2baac14bff32132811 2026-05-10T15:55:55+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-10T15:55:55+00:00 urn:sha1:863640ef172929f003d53d41087005485887e29c The .md equivalent already exists alongside it; with both present and `source_suffix = ['.rst', '.md']`, Sphinx silently preferred the .rst. Deletion removes the shadowing and the only active .rst left in tree (legacy is archived under docs/_rst_legacy/). Restricting source_suffix to ['.md'] prevents future stray .rst files from being picked up, and is what external indexers (e.g. context7) look at when classifying the source format of the docs. 🤖 Generated by [robots](https://vyos.io) 2026-05-10T14:19:31+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-10T14:19:31+00:00 urn:sha1:3fd1787d50dda76619647dd95ea6e1d421204734 The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio (#1899/#1900/#1901) landed in May 2026. The mechanism's surface area (scripts/swap_sources.py, its 245-line test, RTD pre/post hooks, Makefile glue, conf.py dynamic loader) is dead weight, and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. Changes: - Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving subdirectory structure. They remain in the repo for reference; Sphinx excludes the folder via exclude_patterns; Context7 excludes it via excludeFolders. - Strip swap_sources.py invocation from docs/Makefile (swap/restore targets, : swap deps, trap chains). - Strip jobs: pre_build/post_build block from .readthedocs.yml. - Strip rst-*.rst exclude entry and the _md_exclude.txt loader from docs/conf.py; replace with a single _rst_legacy exclude. - Delete scripts/swap_sources.py, tests/test_swap_sources.py, docs/_rst_overrides.txt. - Update context7.json: add docs/_rst_legacy to excludeFolders; fix stale "Branch current tracks…" rule to "Branch rolling tracks…" (default branch was renamed 2026-05-10). - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test; describe _rst_legacy as archive only. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (257), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) 2026-05-10T12:33:32+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-10T12:33:09+00:00 urn:sha1:8dbf8b052075b0fb7af38b7b505260e4f673a998 Cleanup PR following the current→rolling default-branch rename. Drops the now-stale current branch from workflow triggers, flips remaining defaults, and updates documentation/templates. Workflows: - pr-mirror-repo-sync.yml: branches narrowed to [rolling]; workflow_dispatch default and choice list now rolling-only; sync_branch fallback flipped from 'current' to 'rolling'. - check-open-prs-conflict.yml: dropped current from push.branches. - update-version-tags.yml: dropped current from push.branches and from the case statement (now bare 'rolling) TAG=rolling'). - submodules.yml: renamed update_current job, branch update-dependencies-current, and the related commit/title strings to rolling. - update-translations.yml: PR branch update-translations-current renamed to update-translations-rolling. - ai-validation.yml: prompt example updated. Docs/templates: - docs/conf.py: READTHEDOCS_GIT_IDENTIFIER fallback flipped to 'rolling'; comment block updated to describe the rolling branch (the user-facing "(current)" suffix is release-channel terminology and remains). - README.md: branching-scheme section now describes rolling as the default branch, with a note about the rename date. - .github/PULL_REQUEST_TEMPLATE.md: CONTRIBUTING link points at blob/rolling. External @current refs to vyos/.github and vyos/vyos-cla-signatures are left untouched — they reference those repos' default branches and are unaffected by this repo's rename. 🤖 Generated by [robots](https://vyos.io) 2026-05-07T15:23:25+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T14:53:34+00:00 urn:sha1:53eda167df8f0f983ee34fd33e90524dcecb08de Read COOKIEBOT_ID from the environment via conf.py html_context, replacing the hardcoded data-cbid value in layout.html. Guards tightened to {% if gtm_id and cookiebot_id %} so neither GTM nor Cookiebot loads unless both IDs are present. 🤖 Generated by [robots](https://vyos.io) 2026-05-07T15:23:25+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T14:19:41+00:00 urn:sha1:4d8581c0e709848a601384addf3026fb405345fc Move the Google Tag Manager container ID out of the template and into conf.py via os.environ.get('GTM_ID', ''), exposed to Jinja via html_context. Set GTM_ID in the RTD project environment variables. 🤖 Generated by [robots](https://vyos.io) 2026-05-07T06:48:06+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:48:06+00:00 urn:sha1:04541bda8a3d04ecb9824f92d344ec8bd7aa2523 Last residual `.html` reference in the `_write_llms_txt` hook comments — the html_baseurl-empty failure-path comment said "rendering /quick-start.html etc." but the template now emits `.md` URLs. Update the example to `/quick-start.md` to match the actual output. Comment-only change. Same fix applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874), [#1876](https://github.com/vyos/vyos-documentation/pull/1876), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903). Addresses Copilot review feedback on PR #1903. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) 2026-05-07T06:40:47+00:00 Yuriy Andamasov yuriy@vyos.io 2026-05-07T06:40:47+00:00 urn:sha1:ef515553402b9ad86399e0a845f2fccb51aa9b55 The previous comment on `_write_llms_txt` (and on the LLM-Facing Files section in CLAUDE.md) justified the `dirhtml` skip by claiming the template's `.html` URLs wouldn't resolve under `dirhtml` output. That became stale after [#1874@5fe7f9ad](https://github.com/vyos/vyos-documentation/pull/1874/commits/5fe7f9ad) (and parity commits on [#1876](https://github.com/vyos/vyos-documentation/pull/1876)/[#1903](https://github.com/vyos/vyos-documentation/pull/1903)) pivoted the curated template to `.md` URLs — `_copy_md_sources` puts `.md` files at their source-relative paths regardless of builder, so the rendered llms.txt would actually resolve fine under `dirhtml` now. The real reason we skip `dirhtml` is simpler: production publishes only via the `html`/`readthedocs` builders, and we don't render llms.txt for builds we don't ship. Local `make dirhtml` is a developer convenience, not a publish target. Reword the conf.py comment and the CLAUDE.md section to say that plainly. No code-behavior change. Addresses Copilot review feedback on PR #1874 (3 threads on docs/conf.py, docs/_templates/llms.txt.j2, and CLAUDE.md flagging the inconsistency). \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io)