Repository navigation
ci: check external links weekly - #163
Conversation
Add the Links workflow: lychee checks the external links of the pages and the README every Monday and opens (or comments on) one issue "Dead links in the docs" when it finds any. Not a required check, as external sites fail at random. Links between pages stay with the strict MkDocs build. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Krini has no staging branch; its deployment guide is deployment/README.md on dev. Funnel moved its default config to internal/config/examples/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Report only lychee's dead-link exit code and fail on other errors, truncate the issue body, label new issues, skip forks, save the cache per run, and anchor the example.org exclusion. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
actions/cache saves only after successful jobs, and the check fails whenever it finds dead links, so the cache never helped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewer's GuideConfigurationConfigure the weekly lychee workflow and its URL exclusions, with the issue-reporting behavior and repository ignore settings needed to run it safely.
DocumentationExplain the weekly link check and how to run it locally so contributors can reproduce the workflow.
Update the researcher pages to point to the relocated Funnel configuration and the current Krini README and deployment guide.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Linked issuesChecked at commit 8345d34 #156 ci: check links weekly · 3 of 7 met · 3 to check by hand
|
There was a problem hiding this comment.
Hey - I've found 6 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path=".github/workflows/links.yml" line_range="42" />
<code_context>
+ with:
+ args: >-
+ --config lychee.toml --no-progress
+ "docs/**/*.md" README.md
+ output: lychee/out.md
+ fail: false
</code_context>
<issue_to_address>
**Shared reference links go unchecked**
When a page uses a shared external reference defined in `includes/references.md`, `lychee` scans the raw Markdown inputs without MkDocs’ `pymdownx.snippets` auto-append, so references defined in `includes/references.md` have no targets in its inputs and broken URLs there are never reported.
Pass `includes/references.md` to lychee or otherwise expand MkDocs snippets before scanning.
</issue_to_address>
### Comment 2
<location path=".github/workflows/links.yml" line_range="26" />
<code_context>
+ # Forks would open issues in their own copy every week
+ if: github.repository_owner == 'elixir-cloud-aai'
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ permissions:
+ contents: read
</code_context>
<issue_to_address>
**Slow checks skip issue reporting**
When enough links stall or time out during a run, lychee keeps retrying slow links before the report step can run, and the 15-minute job deadline kills the workflow first; no issue or comment is then created for that run.
Increase the job timeout or reduce the per-link timeout/retry budget so Lychee can finish and reach the reporting step.
Also at `lychee.toml:6-7`.
</issue_to_address>
### Comment 3
<location path=".github/workflows/links.yml" line_range="70-74" />
<code_context>
+ } > body.md
+ existing=$(gh issue list --state open --search "in:title \"$title\"" \
+ --json number,title \
+ --jq "map(select(.title == \"$title\")) | .[0].number // empty")
+ if [ -n "$existing" ]; then
+ gh issue comment "$existing" --body-file body.md
+ else
+ gh issue create --title "$title" --body-file body.md \
+ --label "type: bug" --label "priority: medium" \
+ --label "workload: hours" --label "status: triage"
</code_context>
<issue_to_address>
**Duplicate open issues are created**
When another actor creates an issue with the same title after the list call returns no match and before issue creation, `gh issue create` opens a second issue instead of reusing the matching open issue, violating the one-open-issue behavior.
Use an issue-creation flow that rechecks for and reuses a matching open issue before creating one.
</issue_to_address>
### Comment 4
<location path=".github/workflows/links.yml" line_range="16" />
<code_context>
+ contents: read
+
+concurrency:
+ group: links
+ cancel-in-progress: false
+
</code_context>
<issue_to_address>
**Queued checks get replaced**
When a second run queues while one run is active and another is already pending, gitHub keeps at most one pending run per concurrency group and replaces it when another run queues. If a run is active, a scheduled check is pending, and another dispatch arrives, the scheduled check never runs; a transient dead link it would have reported can recover before the later check.
Use a queueing mechanism that preserves each invocation, or otherwise ensure a later dispatch cannot replace a pending scheduled check.
</issue_to_address>
### Comment 5
<location path=".github/workflows/links.yml" line_range="72" />
<code_context>
+ --json number,title \
+ --jq "map(select(.title == \"$title\")) | .[0].number // empty")
+ if [ -n "$existing" ]; then
+ gh issue comment "$existing" --body-file body.md
+ else
+ gh issue create --title "$title" --body-file body.md \
</code_context>
<issue_to_address>
**Reruns post duplicate report comments**
When a run that has already posted its report is rerun while the issue remains open, `gh issue comment` posts the same report again, and the step then exits with status 1, so the rerun adds a duplicate comment and notification to the issue.
Make report posting idempotent so a rerun does not post the same report again.
</issue_to_address>
### Comment 6
<location path="lychee.toml" line_range="5-29" />
<code_context>
+# Links between pages are checked by `mkdocs build --strict`; lychee checks
+# the external ones
+
+max_retries = 3
+retry_wait_time = 5
+timeout = 30
+max_concurrency = 16
+
+# 429: rate limited, so the target exists
+accept = ["200..=299", "429"]
+
+# Only web links; mail addresses can't be verified
+scheme = ["https", "http"]
+include_mail = false
+
+exclude = [
+ # Placeholders and local services in examples
+ '^https?://([a-z0-9-]+\.)*example\.(org|com)(:|/|$)',
+ '^https?://localhost',
+ '^https?://127\.0\.0\.1',
+ # In-cluster service names in examples
+ '^http://cloud-registry/',
+ # Base URLs of GA4GH APIs, which serve no page (their endpoints do)
+ '/ga4gh/[a-z-]+/v[0-9]+/?$',
+ # Need a login or reject bots
+ '^https://registry\.elixir-on\.cloud/auth/',
+ '^https://join\.slack\.com/',
+]
</code_context>
<issue_to_address>
**Complete lychee configuration**
The issue asks for caching and exclusions for <HOST> placeholders in addition to retries, 429 acceptance, and other exclusions. The config has no cache setting and does not exclude those placeholders, which occur in docs/researchers/cli.md.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 6 findings to address first, and if the link checker or its configuration falsely reports failures, the workflow can publish an issue or comment containing that report. Reverting stops future runs but does not undo the public issue or comment already sent.
Blocking findings: .github/workflows/links.yml:42, .github/workflows/links.yml:26, .github/workflows/links.yml:74, .github/workflows/links.yml:16, .github/workflows/links.yml:72, and 1 more
Also check includes/ (abbreviations and shared references appended by pymdownx.snippets), and give the job 30 minutes so slow hosts don't kill it before the report step. From the Sourcery review. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Links(.github/workflows/links.yml, joblinks/Link check): lychee checks the external links ofdocs/**/*.mdandREADME.mdevery Monday at 06:00 UTC and on manual dispatch. Not a required check, as external sites fail at random; links between pages stay withmkdocs build --strict.lychee.tomlexcludes placeholders, localhost, in-cluster names, login-only pages, Slack invites and GA4GH API base URLs (which serve no page).README.mdexplains how to run the check locally.stagingbranch, the deployment guide isdeployment/README.mdondev).https://protes.rahtiapp.fi/(404) inoperators/services/protes.mdandresearchers/index.md; the first run will report it.Closes #156
Verification
lychee 0.21.0 --config lychee.toml "docs/**/*.md" README.md: 743 links, 426 OK, 315 excluded, 2 errors (the proTES URL above).python scripts/check_names.py,mkdocs build --strict,pytest(25 passed, 100 % coverage): pass.gh workflow run links.yml --repo elixir-cloud-aai/docsonce to confirm; it should open one issue for the proTES URL.Declined review findings
permissionsat workflow and job level: intended (default read-only,issues: writeonly for the job).Open questions
None
🤖 Generated with Claude Code