ci: repository hygiene — pin actions, Dependabot, link check

[sstruzik]

The repository-hygiene PR, kept separate from the restructure in #54 so that one stays about documentation. Merges after #54 — see Merge order below.

Three things: pin the actions, let Dependabot propose updates instead of them arriving silently, and actually check the links in the published site.

---

1. Actions pinned to commit SHAs

Every uses: in the preview workflow floated on a major tag, so the code CI runs was decided by wherever the upstream maintainers last moved that tag rather than by anything here.

Not hypothetical: while diagnosing a preview failure on #54 I traced it to lib/get-deployed-commit.sh in pr-preview-action — a script that did not exist until upstream commit 52a1f7b1 (2025-12-24). It started running in our CI, and later failed a run, without a line changing in this repo.

Reference	Pinned to
actions/checkout	a37ce912… — v3.7.0
actions/setup-python	7f4fc3e2… — v4.9.1
rossjrw/pr-preview-action	ffa7509e… — v1.8.1

No behaviour change — every SHA is what the tag resolved to on the last green run.

What is actually being pinned

Not Python dependencies — GitHub Actions, a different layer. An action is reusable CI automation living in someone else's repository: when a workflow says uses: actions/checkout@v3, the runner clones that repository and executes the code inside. actions/checkout and actions/setup-python are bundled Node.js; pr-preview-action is a composite of 11 YAML steps that internally calls JamesIves/github-pages-deploy-action and its own shell scripts. That nesting is why the recent failure was hard to place: one "Deploy preview" step is eleven deep.

Two properties make it worth holding still: the code executes with our secrets in scope (BUILD_PREVIEW_TOKEN has write access to OasisLMF/PreviewDocs), and a major tag is a mutable pointer.

build-deploy.yml is not pinned here — #54 rewrites that workflow for versioned deploys, so it is pinned in that PR instead (ed9c4d8). Between the two, every action reference ends up pinned.

2. Dependabot

github-actions, so pinning does not mean stagnation: each upstream release becomes a reviewable pull request instead of a silent tag move.

Plus pip, for the docs toolchain. requirements.txt is generated by pip-compile and carries its header, so Dependabot regenerates it with pip-compile rather than hand-editing pinned lines. Grouped into one weekly PR: almost everything alerted is transitive — only requests and jinja2 are direct entries in requirements.in — so a bump means a recompile either way, and one recompile reviews better than a PR per package.

Why this is hygiene rather than urgent: the 43 alerts on the default branch describe main's stale 89-line pin set, and #54 already recompiled it to 122 lines. That merge alone clears the critical advisory (h11 0.14.0 → 0.16.0, the patched version) and 13 of the alerts, since mistune is no longer a dependency at all. Nothing here ships to users — this repository only builds documentation.

3. Link check over the assembled site

check_links.py, run weekly. Two checks, because they are different problems:

	What	Cost	Fails the run?
internal	every in-site link resolves to a file in the tree	0.9s / 55k links	yes — offline and deterministic, so a failure is always real
external	every distinct http(s) URL answers	~20s / 135 URLs	no by default (--fail-on-external opts in)

The internal check is the important half: the orchestrator rewrites cross-component links to page-relative paths, so a page renamed in one component silently breaks links from another. It is also what replaces the build-time verification dropped in ODS_Tools#289.

Weekly plus a button, deliberately not on pull requests — 100+ third-party requests per PR invites the 429/503 failures this repo hit twice, and link rot is a maintenance chore, not a merge gate. Sphinx's own linkcheck builder runs per project against source and cannot see the assembled tree, hence a script rather than a builder.

It has already earned its place. The first run found 3 broken in-site links and 15 dead external ones across four repositories — a deleted platform-2.0 branch, a gone OasisAPIClient repo, the pre-split ODS path, an email address wrapped in http:// — since fixed or triaged. The ignore list covers what is not checkable rather than what is inconvenient: localhost service UIs in deployment examples, *.example.com placeholders, Stack Overflow / Stack Exchange (which 403 anything automated), and docs.precisely.com, whose TLS chain does not verify from a plain runner though the pages are fine in a browser.

---

Merge order

After #54, and rebase on main once it lands. The link check builds the aggregated site via ./build.sh, and orchestrate.py / modules.json do not exist on main yet — on today's main that script builds the old flat site. The workflow is schedule/dispatch-only so it cannot fail this PR's checks, but the weekly job would check the wrong tree if this merged first.

Also expect the two PRs to conflict once in build-preview.yml: #54 changes the Python version there while this pins the uses: line directly above it. I trial-merged both orders — each hits the same two-line conflict, so the order only decides where it lands. Resolution is #54's step name with the pin from here:

      - name: Set up Python 3.12
        uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c  # v4.9.1
        with:
          python-version: '3.12'

Deliberately left

The pins freeze versions already behind — actions/checkout v3.7.0 (latest v7.0.1) and actions/setup-python v4.9.1 (latest v7.0.0), both of which the runner warns about for targeting Node.js 20. That keeps this a pure no-behaviour-change hardening; Dependabot will raise those major upgrades as separate pull requests that can be validated on their own.

requirements.txt has 122 exact == pins but 0 hash pins, so the build trusts whatever sits at that version on PyPI. pip-compile --generate-hashes would close that, and is the more valuable follow-up.

Pin GitHub Actions to commit SHAs, add Dependabot for actions and the docs toolchain, and add a weekly link check over the published site.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://OasisLMF.github.io/PreviewDocs/pr-preview/pr-55/
Built to branch gh-pages at 2026-08-19 08:45 UTC. Preview will be ready when the GitHub Pages deployment is complete.