devantler-tech / devantler-tech/ksail

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

Closed
#6,473 3 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.