A transient third-party 5xx fails CI: lychee gates on link availability, not link validity

[devantler]

🤖 Generated by the Agentic Engineer

Evidence

MegaLinter failed on an unrelated Go-only PR (#6472, head df3ef863), run 30877067429:

Errors in CONTRIBUTING.md
[503] https://golangci-lint.run/docs/welcome/install/ (at 52:3) | Rejected status code: 503 Service Unavailable

SPELL_LYCHEE reported Found 1 error(s), which failed the whole 🧹 Lint - mega-linter check. Summary for that run: 174 links, 103 successful, 1 error — this one.

The link is not broken. Re-requested from this host a few minutes later it returned HTTP 200. The PR touches only pkg/svc/credentials/*.go and does not modify CONTRIBUTING.md, so nothing in the change could have caused or fixed it.

Problem

The link check currently gates on a third-party host being up at the moment CI runs, not on whether our links are correct. A 5xx is the remote service failing, which is outside this repository's control and self-resolving — unlike a 404, which is a real defect in our docs and should keep failing.

Because CONTRIBUTING.md is on main, any PR can be failed by an unrelated upstream outage. That is a red check with no action available to the PR author except waiting, and it trains the habit of dismissing MegaLinter failures as noise — which is how a real link regression gets waved through.

Expected behaviour

Transient remote failures should not fail the build; genuine link defects still should.

lychee supports this directly in lychee.toml:

• accept — treat specific status codes as success,
• max_retries / retry_wait_time — retry before reporting,
• and 429 deserves the same treatment as 5xx (rate limiting is also not a broken link).

Acceptance criteria

• A simulated 5xx (and 429) from a linked host does not fail the lint check, proven by a test or a pinned fixture rather than by observation.
• A 404 still fails it — a control, so the carve-out cannot widen into "any link error is ignored".
• The chosen retry/accept policy is recorded in lychee.toml with a comment naming why each accepted code is transient.
• Verified against the real CONTRIBUTING.md link set.

Size: small — configuration plus a control test.

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• bug(ci): a transient 5xx on one link fails the whole lint job #6398

🔗 Related PRs

#5657 - ci: ignore flaky goreportcard.com badge links in lychee [merged]
#5907 - ci(mega-linter): disable betterleaks secret scanner [merged]
#5994 - ci(coderabbit): make docstring-coverage pre-merge check non-blocking [merged]
#6445 - fix(ci): reject unsafe generated file additions [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[devantler]

🤖 Generated by the Agentic Engineer

Third occurrence, and this one narrows the remedy. main went red at 585c8e5f5f
(run 33180904010, 14:38:26Z) on a
single lychee error:

Errors in server.json
[ERROR] https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json (at 2:15)
        | I/O error (ConnectionReset). Check network connectivity and server status

Same signature as this issue: 113 unique links, 104 successful, 1 error, and the failure is
unrelated to the merge that produced the head (that commit touched go.mod/go.sum and two action
files; server.json has not changed since April).

Verified transient two ways rather than asserted:

• The URL returned HTTP 200 on 3/3 attempts from the agent host immediately afterwards.
• Re-running the failed job on the identical commit turned it green (attempt 2, mega-linter
  success). Same code, same links — only the network differed.

Why this matters for the proposed fix. The remedy sketched above is status-code based
(accept treating a transient 5xx as non-fatal). This failure carried no status code at all — it
is a connection reset at the transport layer, which accept cannot express. lychee.toml already
sets max_retries = 3 / retry_wait_time = 2, and the whole pass took 4.48s, so the three retries
again completed well inside the outage window.

So a complete fix needs to cover I/O-level failures, not just 5xx status codes — and the retry
budget needs to actually span a short outage rather than three attempts inside ~4s. Excluding the
host is still the wrong remedy here for the reason this issue already gives: it would suppress a real
404 on the same link.

[devantler]

🤖 Generated by the Agentic Engineer

Two more occurrences on 2026-09-14, both on GitHub release downloads

Both failures were on the same PR, #7036, which changes only Go files under pkg/cli/cmd/cluster/:

Head	Run	lychee error
6d9d37d4	34855714963	.goreleaser.yaml: [504] https://github.com/devantler-tech/ksail/releases/latest/download/install.sh
d55df251	34864050542	.github/workflows/cd.yaml: [500] https://github.com/modelcontextprotocol/registry/releases/download/v1.7.8/registry_1.7.8_checksums.txt

Controls from the same hour:

• MegaLinter passed on main (15:17Z) and on fix(ci): report an unreachable GitHub API as an outage, not rate-limit exhaustion #7037 (15:40Z).
• The first failure passed on re-run.
• The PR touches neither .goreleaser.yaml nor cd.yaml.

What this adds to the evidence: the two failures hit different GitHub release-download URLs about 90 minutes apart. So github.com/.../releases/download/... links fail intermittently with a 5xx, independent of any one project. Every PR runs this check, so each outage fails an unrelated PR and costs a full re-run.

Related: #6398 records the same failure mode for our own docs host. Its constraint still applies to any fix here: a genuine outage of ksail.devantler.tech must stay visible, while a third-party 5xx should not fail the build.

[devantler]

🤖 Generated by the Agentic Engineer

Resolved by #7083. Closing as completed.

#7083 (merged 2026-09-16, 41c7d62f) implements this issue's policy in lychee.toml. Checked against each acceptance criterion:

• A transient 5xx or 429 does not fail the check. accept now includes 502..=504; 429 was already accepted. fix(ci): stop a momentary 5xx on a valid link failing the lint job #7083's red/green run used a local status server with the old and new config: 502, 503 and 504 failed before (exit 2) and pass now (exit 0). This also covers the 504 on GitHub release downloads reported above.
• 404 still fails. In the same run, 404 and 500 failed under both configs.
• Every accepted code has a comment in lychee.toml saying why it is transient. The comment also corrects the old one. lychee 0.24.2 does not retry a 5xx response: it makes one request and fails. It does retry timeouts. Because of that, only accept can keep a brief outage from failing an unrelated PR.
• Tested against the real link set. MegaLinter passed with the new config on main at 41c7d62f and 35672daa.

Deliberate decision: a 500 still fails. Unlike 502/503/504, a 500 cannot be told apart from a real server-side defect. Accepting it would widen the carve-out toward "any error is fine", which the second criterion rules out. So the intermittent 500 from modelcontextprotocol/registry above is still reported. If GitHub release downloads keep returning intermittent 500s, the next step is a per-host rule, not a global one.

Not done: the proof above was measured against a local server when #7083 was made. There is no fixture pinned in the repository, because that would add a lychee binary dependency to the test suite just to test a config file. Reopen this issue if a pinned fixture turns out to be worth that cost.