ci: add advisory external-link checker for docs and root prose#653
Conversation
`mkdocs build --strict` validates in-repo links and the source_links.py rewrites but never checks external https URLs, so a dead third-party link merges silently and rots (#626: a FreeRTOS-Plus-FAT 404 sat on main until found by chance). Adds a separate `docs-links` workflow running lychee over docs/ plus the repo-root prose files: - Advisory on pull requests (fail: false) and not a required status check — a merge must not fail because someone else's host had a bad minute. - Blocking on the weekly schedule (fail: true) so link rot that appears without us touching a file surfaces as a failed run. - Retries with backoff, a real user agent, and accept 429 (see lychee.toml). - Own-repo github.com self-links excluded (already covered by the strict build); known suspects left in scope so the run gives a verdict. Separate workflow (not a job in ci.yml) so the weekly cron doesn't drag the whole CI suite along. Closes #626 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
WalkthroughAdds a GitHub Actions lane that checks external documentation links on pull requests, weekly, and manually. Lychee configuration defines retries, timeouts, accepted responses, HTTP(S) scope, and repository self-link exclusions. Two documentation URLs are corrected. ChangesExternal documentation links
Estimated code review effort: 2 (Simple) | ~10 minutes Sequence Diagram(s)sequenceDiagram
participant GitHubActions
participant Repository
participant LycheeAction
participant ExternalDocumentationHosts
GitHubActions->>Repository: checkout documentation sources
GitHubActions->>LycheeAction: check docs and root Markdown files with lychee.toml
LycheeAction->>ExternalDocumentationHosts: request external HTTP(S) URLs
ExternalDocumentationHosts-->>LycheeAction: return HTTP status results
LycheeAction-->>GitHubActions: report link-check outcome
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs-links.yml:
- Around line 19-30: Add workflow-level concurrency to the docs link-check
workflow, using a shared group keyed by the workflow and ref so pull_request,
workflow_dispatch, and scheduled runs are serialized. Configure cancellation of
in-progress runs only for pull_request events, while allowing scheduled and
manual runs to finish.
- Around line 45-59: Update the lychee-action configuration in the docs-links
workflow to set failIfEmpty to the same schedule-based guard as fail, so empty
PR and manual scans remain non-blocking while scheduled scans still fail when
empty.
In `@lychee.toml`:
- Line 24: Update the self-repository exclusion regex in the configuration to
require a repository boundary after “solid-syslog,” such as a slash, query,
fragment, or end of string. Preserve matching for the intended repository while
preventing matches for names like “solid-syslog-extra.”
- Line 14: Update the lychee `accept` configuration to accept the full
successful HTTP status range from 200 through 299 while retaining 429 as
accepted.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: eeaab043-2eff-492d-b9c2-dc9c0deb6bcf
📒 Files selected for processing (2)
.github/workflows/docs-links.ymllychee.toml
The docs-links lane's first run flagged two 404s: - integrating-mbedtls.md: the Mbed TLS porting KB page moved to an uppercase `-OS/` slug (casing-only change upstream). - security/release-verification.md: the sigstore cosign install page moved under a `/cosign/` path prefix. Both replacements verified 200. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Add workflow-level concurrency (cancel superseded pull_request runs only) so PR, manual, and weekly runs don't overlap and burn external crawl quota. - Set failIfEmpty to the same schedule guard as fail — v2.9.0 defaults it to true, so an empty scan must not fail a PR or manual run. - Widen accept to 200..=299 (any 2xx is success, not just 200..=206). - Bound the self-repo exclusion regex with (?:[/?#]|$) so it can't also match a hypothetical solid-syslog-extra. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
☀️ Quality Summary Created by Quality Monitor v4.15.0 (#82d77af). More details are shown in the GitHub Checks Result. |
1 participant
Purpose
Implements #626 (S23.15, epic #246) and item 7 of the 0.1.0 milestone. Nothing
currently validates external
https://URLs in the docs —mkdocs build --strictonly resolves in-repo links and thesource_links.pyrewrites — so adead third-party link merges silently and rots. This is not hypothetical: a
FreeRTOS-Plus-FAT 404 sat on
mainuntil found by chance.Change Description
New
docs-linksworkflow (separate fromci.yml) running lychee overdocs/plus the repo-root prose (README,CONTRIBUTING,CODE_OF_CONDUCT,SECURITY,SUPPORT):fail: false) and intentionally not a requiredstatus check — a merge must not fail because someone else's docs host had a
bad minute.
fail: true, Mondays 06:17 UTC) so linkrot that appears without us touching a file surfaces as a failed run — the
exact way the Plus-FAT 404 slipped in. Plus
workflow_dispatchfor manualruns.
accept 429— a timeout is not a404 (config in
lychee.toml).github.com/cososo-ltd/solid-syslogself-linksare excluded — the strict build already resolves the ~99
source_links.pylinks pre-rewrite. Known suspects are left in scope so the run gives a
verdict.
ci.yml) so the weekly cron doesn't drag thewhole CI suite along.
Action pinned by SHA (lychee-action v2.9.0), per repo convention.
Test Evidence
lychee.tomlvalidated as well-formed.http(s)://elm-chan.org/fsw/ff/nowreturns 200 on both schemes (it was refusing 443 / silent on 80 when
added) — that concern is cleared.
Areas Affected
.github/workflows/docs-links.ymlandlychee.tomlonly. No source, build, orexisting-CI changes. New check is advisory (not in the required-checks set), so
branch protection is unchanged.
Follow-ups (noted, out of scope)
validation.links.anchors: infoinmkdocs.yml): a brokeninternal
#fragmentstill passes the strict build silently. A differentmechanism (checking the built site's HTML); worth a separate story.
Closes #626
🤖 Generated with Claude Code
Summary by CodeRabbit