Repository navigation
Make the nightly link check report its results - #1175
Merged
Merged
Conversation
Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
The image host answers 429 with a Retry-After header. Sphinx linkcheck waits for the full Retry-After time and does not cap it. The check then does not end, and GitHub cancels the job at its 6-hour limit. Refs: napari#1174 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
The default token does not have write access to issues. The issue step fails with "Resource not accessible by integration". A permissions block sets each scope that it does not name to none, so the block also grants contents read for the checkouts. Refs: napari#1174 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
GitHub states the two timeouts as follows: - steps[*].timeout-minutes: "The maximum number of minutes to run the step before killing the process." - jobs.<job_id>.timeout-minutes: "The maximum number of minutes to let a job run before GitHub automatically cancels it." A cancelled job skips the failure() issue step. A full run takes about 45 minutes, so 120 minutes gives headroom. https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes Refs: napari#1174 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
The report otherwise exists only in the issue body and the run log. It is lost when the issue step fails and when the log expires. Refs: napari#1174 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
setup-python reads cache-dependency-path only when cache is set, so the existing setting does nothing. The listed docs/requirements.txt no longer exists. Key the cache on the files the install step uses: napari/pyproject.toml and the py3.12 docs constraints file. Assisted-by: claude-code:claude-fable-5-1 [Emily]
A lookup step finds the open "Link Checker Report" issue and passes its number to the issue action. The action then updates that issue. When none is open, the number is empty and the action creates one. Assisted-by: claude-code:claude-fable-5-1 [Emily]
The job checks out this repo twice: once into the workspace root and once into docs/. Every later step reads docs/ or napari/, so the root copy is unused. Assisted-by: claude-code:claude-fable-5-1 [Emily]
The default is one attempt per URL, so a transient timeout or 429 lands in the report as a broken link. Assisted-by: claude-code:claude-fable-5-1 [Emily]
lundybernard
force-pushed
the
lb/linkcheck-report
branch
from
October 21, 2026 15:23
6cd8b3a to
f7d575e
Compare
TimMonko
approved these changes
Oct 22, 2026
TimMonko
left a comment
Member
There was a problem hiding this comment.
Thanks for this great fix!
I look forward to seeing if it makes a PR.
We discussed briefly at the docs meeting and a few ideas:
- we would have to restructure this for PRs by not having it open an issue and just failing. Unsure if its currently worth on PRs
- Also want to add the option to run this locally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overhaul the nightly link check job,
It was not reporting broken links due to missing permissions,
and had several other defects worth fixing in this pass.
🤖 AI text below 🤖
References and relevant issues
Refs #1174
Description
linkcheck_ignore. The host answers 429 withRetry-After, Sphinx waits with no cap, and GitHub cancels the job at 6 h.contents: readandissues: writeto the job. The issue step failswithout write access to issues.
timeout-minutes: 120to the link checker step. A step timeout fails thestep, so the issue step still runs. A job timeout cancels the job.
output.txtas thelinkcheck-reportartifact on every run.setup-pythonpip cache. The step setcache-dependency-pathwithout
cache, so it cached nothing, and it listed a deleted file.per failed run. A lookup step passes the open issue number to the action.
linkcheck_retries = 2, so a transient timeout or 429 does not land inthe report as a broken link.
Verification:
pre-commitandactionlintpass at each commit.Reviewer notes
change the cron to
0 0 * * 0.fresh one.
(
workflow_dispatch) after the merge.prep-docs, on the expired certificate atnitrc.org (Prefetch only when needed and use persistent cache across runs #1157). That run makes no report.