devantler-tech / devantler-tech/ksail
A transient third-party 5xx fails CI: lychee gates on link availability, not link validity
- Dominant language
- Go
- Stars
- 165
- Forks
- 12
- Avg merge
- 5h 51m
- Merged PRs (30d)
- 347
Description
> 🤖 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.
Contributor guide
Research direction
Start with lychee.toml and the CI check that runs SPELL_LYCHEE against CONTRIBUTING.md. Add a pinned fixture or test covering 5xx and 429 as transient while keeping 404 failing, document the rationale in lychee.toml, and verify the policy against the real CONTRIBUTING.md link set.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- ci-cd, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100