Skip to content

ci: stop the link check failing on transient network errors - #78

Merged
ZhuYaoHui1998 merged 2 commits into
Seeed-Projects:mainfrom
Chirag6722:fix/link-check-transient-failures
Sep 7, 2026
Merged

ci: stop the link check failing on transient network errors#78
ZhuYaoHui1998 merged 2 commits into
Seeed-Projects:mainfrom
Chirag6722:fix/link-check-transient-failures

Conversation

@Chirag6722

Copy link
Copy Markdown

Closes #77

What this changes

Two flags on the existing lychee step. No new files, no new dependencies.

             --max-retries 3
+            --retry-wait-time 2
             --timeout 30
             --accept 200,206,403,429
+            --accept-timeouts

Why. Run 33466366735 failed on the #71 branch at 03:28 UTC on 2026-09-01, and #71 was merged at 03:31 — three minutes later. Merging was the correct call: the failure was not real. But a check that goes red for reasons unrelated to the pull request is a check people learn to dismiss, and the next genuine 404 earns the same three-minute dismissal. That is the failure mode this addresses — not the one red run.

--accept-timeouts is upstream's own answer to this: "accept timed out requests and return exit code 0 when encountering timeouts but not any other errors." A host that does not answer within 30 s tells us nothing about whether the link is dead. A delisted product still answers 404, and that still fails the build — which is the entire purpose of the job, and it stays intact.

--retry-wait-time 2 matters because the three retries currently fire with lychee's 1 s default gap, so all three land inside the same bad two seconds.

Verification

  • The failure was transient, not a real broken link. main as it stands: 0 broken relative links; 203 external links, 111 checked after .lycheeignore, 0 failures. The Rebot_Arm_description/ package docs: add reusable ReBot Arm description package #71 added contains no external links at all and its one relative link resolves. The scheduled run on 2026-08-31 passed, and so did the PR run on 2026-09-03.
  • Both flags exist in the lychee the action installs. Confirmed against the released lychee-v0.24.2 source rather than the docs: accept_timeouts is declared in lychee-bin/src/config/mod.rs at that tag, and check.rs branches on it (accept_timeouts() → is_success_ignoring_timeouts()), which is precisely the semantics claimed above. retry_wait_time is declared in the same file.
  • actionlint passes; the file parses and the assembled args string was asserted after the edit.
  • This PR's own link-check run exercises the change — the workflow triggers on its own path, and lychee exits non-zero on an unrecognised flag, so a green run here is direct evidence the flags are accepted by the installed binary.

I could not run lychee locally to demonstrate a timeout being downgraded; that would mean downloading a release binary onto this machine, which I would rather not do to prove a two-flag change. The upstream source is the stronger evidence anyway.

Two things deliberately left out

  • No result caching. It would cut outbound requests further, but a cached success can hide a link that broke earlier the same day. This check is more useful slow and honest.
  • 5xx and connection resets still fail. Only timeouts are downgraded. Treating server errors as non-fatal would be going too far — a 500 that persists is a real problem worth seeing.

Still open from #64

Unrelated to this PR, but #64 was closed without an answer to the two BOM contradictions it raised — the M4*7 vs M4*8 dowel-pin length, and the CAN power-distribution board that only the Chinese BOM lists. Both are still live in the docs. Happy to send that follow-up whenever someone can say which way they go.

🤖 Generated with Claude Code

Run 33466366735 failed on the Seeed-Projects#71 branch over a network error rather
than a broken link, and Seeed-Projects#71 was merged three minutes later. Merging was
correct — main checks clean today, and that PR added no external links
at all — but a check that goes red for reasons unrelated to the pull
request is a check people learn to dismiss, and the next genuine 404
gets the same three-minute dismissal.

- --accept-timeouts: a host that does not answer within the timeout says
  nothing about whether the link is dead. A delisted product still
  answers 404, and that still fails the build, which is the whole point
  of the job. Available in the released lychee v0.24.2 the action pulls.
- --retry-wait-time 2: the three retries fired back-to-back with the 1s
  default, so all three landed inside the same bad moment.

Not included: caching successful results between runs. It would cut
outbound requests, but a cached success can hide a link that broke
earlier the same day, and this check is more useful slow and honest.

A transient 5xx or connection reset still fails. Only timeouts are
downgraded — a 500 that persists is a real problem worth seeing.

Closes Seeed-Projects#77

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Passing --accept replaces lychee's default (100..=103,200..=299) rather
than adding to it, so naming only 200 and 206 makes every other success
an error. The YouTube link in the READMEs answers 204 to some requests,
which would fail the build for a link that is alive — another false red
of exactly the kind this branch is about.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Chirag6722

Copy link
Copy Markdown
Author

Two updates.

This PR's red check is not this PR. The link check here is failing on links that were fixed weeks ago in #58, #61 and #63 — the Feishu redirect, wiki.seeedstudio.com/Sensor/IMU/, the readme.md case mismatch. Those regressed on main: merge commit 11f09f7 resolved README conflicts in favour of a stale local branch and reverted them, along with @LAN-GER's community row from af00e42. Written up in #79 and fixed in #80, which is green. Once that merges, this goes green too — the red here is the check doing its job on a real regression.

Added a second commit (39af44f): --accept 200,206,403,429--accept 200..=299,403,429. Passing --accept replaces lychee's default range (100..=103,200..=299) rather than adding to it, so naming only 200 and 206 turns every other 2xx into an error. The YouTube link in the READMEs answers 204 to some requests — a live link that would fail the build. Same class of false red as the rest of this PR; I found it while verifying #80.

Suggested order: #80 first, then this.

@ZhuYaoHui1998
ZhuYaoHui1998 merged commit 3ca1ba4 into Seeed-Projects:main Sep 7, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Link check fails on transient network errors, and the first false red was merged past in three minutes

2 participants