Skip to content

Make the nightly link check report its results - #1175

Merged
TimMonko merged 9 commits into
napari:mainfrom
lundybernard:lb/linkcheck-report
Oct 22, 2026
Merged

TimMonko merged 9 commits into
napari:mainfrom
lundybernard:lb/linkcheck-report

Conversation

@lundybernard

Copy link
Copy Markdown
Contributor

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

  • Fix the schedule comment. The cron runs every day at midnight UTC.
  • Add the Tabuaeran image URL to linkcheck_ignore. The host answers 429 with
    Retry-After, Sphinx waits with no cap, and GitHub cancels the job at 6 h.
  • Grant contents: read and issues: write to the job. The issue step fails
    without write access to issues.
  • Add timeout-minutes: 120 to the link checker step. A step timeout fails the
    step, so the issue step still runs. A job timeout cancels the job.
  • Upload output.txt as the linkcheck-report artifact on every run.
  • Enable the setup-python pip cache. The step set cache-dependency-path
    without cache, so it cached nothing, and it listed a deleted file.
  • Update one open "Link Checker Report" issue instead of opening a new one
    per failed run. A lookup step passes the open issue number to the action.
  • Drop the unused checkout of this repo into the workspace root.
  • Set linkcheck_retries = 2, so a transient timeout or 429 does not land in
    the report as a broken link.

Verification: pre-commit and actionlint pass at each commit.

Reviewer notes

  • The cron runs daily, and each failed run opens a new issue. For a weekly run,
    change the cron to 0 0 * * 0.
  • Closing the report issue resets the lookup. The next failed run opens a
    fresh one.
  • The permission fix needs a real run. Start the workflow by hand
    (workflow_dispatch) after the merge.
  • A run can still fail earlier, in prep-docs, on the expired certificate at
    nitrc.org (Prefetch only when needed and use persistent cache across runs #1157). That run makes no report.

@github-actions github-actions Bot added documentation Improvements or additions to documentation maintenance CI, dependencies, and other maintenance labels Oct 20, 2026
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

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]

@TimMonko TimMonko left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. 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
  2. Also want to add the option to run this locally.

@TimMonko TimMonko added this to the 0.10.0 milestone Oct 22, 2026
@TimMonko
TimMonko merged commit a8499df into napari:main Oct 22, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation maintenance CI, dependencies, and other maintenance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants