From 4dc77a51a2a3db66842acfc78c5d7c215680cd9f Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 20 Oct 2026 08:26:43 -0700 Subject: [PATCH 1/2] ci: clarify Lychee cache misses and manual refreshes Signed-off-by: Ralf W. Grosse-Kunstleve --- .github/actions/lychee-links/action.yml | 22 +++++++++++++++++++++- .github/workflows/lychee.yml | 2 +- ci/README.md | 21 ++++++++++++++++++--- 3 files changed, 40 insertions(+), 5 deletions(-) diff --git a/.github/actions/lychee-links/action.yml b/.github/actions/lychee-links/action.yml index 45ba88fc772..49b645aabc0 100644 --- a/.github/actions/lychee-links/action.yml +++ b/.github/actions/lychee-links/action.yml @@ -84,6 +84,7 @@ runs: echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}" - name: Restore successful link checks + id: cache-restore # Refresh mode deliberately skips earlier URL results. if: ${{ inputs.refresh != 'true' }} uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 @@ -93,6 +94,25 @@ runs: restore-keys: ${{ steps.cache.outputs.prefix }} enableCrossOsArchive: true + - name: Explain a missing shared Lychee cache + # Prefix restores are normal; cache-hit only identifies exact key matches. + if: ${{ inputs.refresh != 'true' && steps.cache-restore.outputs.cache-matched-key == '' }} + shell: bash --noprofile --norc -euo pipefail {0} + env: + KIND: ${{ inputs.kind }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/workflows/lychee.yml + run: | + message="No shared Lychee ${KIND} cache was restored for this checker configuration. Checking links without this baseline may take longer and make more network requests." + context="This is expected after checker changes in a PR; a refresh on ${DEFAULT_BRANCH} cannot seed settings that exist only in a PR." + hint="For an unexpected miss on ${DEFAULT_BRANCH}, maintainers can run CI: Lychee checks and caches (lychee.yml) on ${DEFAULT_BRANCH} with refresh-cache enabled." + echo "::notice title=Lychee ${KIND} cache::${message} ${context} ${hint} ${WORKFLOW_URL}" + { + printf '### Lychee %s cache\n\n' "$KIND" + printf '%s\n\n%s\n\n%s\n\n' "$message" "$context" "$hint" + printf '[Open the cache refresh workflow](%s).\n' "$WORKFLOW_URL" + } >> "$GITHUB_STEP_SUMMARY" + - name: Check links through the configured pre-commit hook shell: bash --noprofile --norc -euo pipefail {0} env: @@ -107,7 +127,7 @@ runs: --report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json" - name: Publish fresh successful link checks - # Only nightly refreshes publish, so every pull request restores the same + # Only refresh runs publish, so every pull request restores the same # baseline. Saving keeps original timestamps and never caches failures. if: ${{ !cancelled() && inputs.refresh == 'true' }} uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 6a3f519ce9b..5a3eb40e346 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -7,7 +7,7 @@ # results. Nightly starts afresh, reports unresolved links as warnings, and is # the only producer of both shared baselines. -name: "CI: Documentation links" +name: "CI: Lychee checks and caches" on: workflow_call: diff --git a/ci/README.md b/ci/README.md index 47448144ee0..a67f7362b5e 100644 --- a/ci/README.md +++ b/ci/README.md @@ -88,9 +88,9 @@ existing allowance for at most ten distinct HTTP 429 URLs. ### Shared URL Caches -Nightly is the only producer. It skips restoring, checks afresh, and publishes -successful results; every other job restores the newest baseline and never -publishes. Failed URLs and filesystem targets are never cached. Successes keep +Nightly and manual refreshes skip restoring, check afresh, and publish +successful results; ordinary checks restore the newest baseline and never +publish. Failed URLs and filesystem targets are never cached. Successes keep their original timestamps and expire after three days, so a missed nightly refresh does not break reuse, but a link that breaks after a nightly success can stay unnoticed for up to 72 hours. @@ -104,6 +104,21 @@ fragments and Lychee's cache does not record which validation ran. URL results are shared across operating systems; pre-commit's installed environments keep their OS- and Python-specific caches. +#### Refreshing Shared Caches + +To rebuild both shared caches manually, open +[CI: Lychee checks and caches](https://github.com/NVIDIA/cuda-python/actions/workflows/lychee.yml) +(`.github/workflows/lychee.yml`), select the default branch, and enable +`refresh-cache` before choosing **Run workflow**. This runs the cache refresh +without the rest of nightly CI. + +Checks that restore no matching baseline add a notice and a job-summary hint. +They still check links, with potentially more runtime and network traffic. +Checker changes in a PR intentionally start with a cold cache; refreshing the +default branch cannot seed a cache for settings that exist only in that PR. +Refreshing rebuilds cached successes; broken links and upstream rate limits +still need their usual investigation. + ### Repository Links Documentation can link to a path added or moved in the same PR using its From 3119227492c7eba1e7666c93cdc2fe2922dec7ab Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 20 Oct 2026 08:51:05 -0700 Subject: [PATCH 2/2] Adopt CodeRabbit suggestion. --- .github/workflows/lychee.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 5a3eb40e346..e73df49a34b 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -4,8 +4,8 @@ # Warm authored and rendered link caches through the configured pre-commit # hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered -# results. Nightly starts afresh, reports unresolved links as warnings, and is -# the only producer of both shared baselines. +# results. Nightly and manual dispatches with refresh-cache=true start afresh, +# report unresolved links as warnings, and can produce both shared baselines. name: "CI: Lychee checks and caches"