ci: retry Lychee label lookups and fall back to the default policy

Read current PR labels once in the shared composite action. Retry failed or malformed lookups three times with 5/10-second delays, then warn and retain the normal link policy. An unconfirmed label never enables the override.

Expose the early label decision to the authored pre-commit job so other hooks still run after an ordinary labeled link failure. Nightly and default-branch calls do not query PR labels.

Signed-off-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>

Author: rwgk

.github/actions/lychee-links/action.yml

@@ -17,12 +17,51 @@ inputs:
   refresh:
     description: "Check links afresh and publish the successful results as the new baseline"
     default: "false"
+  pr-number:
+    description: "PR whose current maintainer override label should be read; empty skips the lookup"
+    default: ""
+
+outputs:
+  allow-429:
+    description: "Whether the current PR label explicitly enables the HTTP 429 override"
+    value: ${{ steps.lychee-policy.outputs.allow-429 }}
 
 # Callers provide Python and the checked-out repository; the build of any
 # rendered documentation must already be complete.
 runs:
   using: composite
   steps:
+    - name: Read the PR's Lychee rate-limit override
+      id: lychee-policy
+      shell: bash --noprofile --norc -euo pipefail {0}
+      env:
+        GH_TOKEN: ${{ github.token }}
+        GH_REPO: ${{ github.repository }}
+        PR_NUMBER: ${{ inputs.pr-number }}
+      run: |
+        allow_429=false
+        if [[ -n "$PR_NUMBER" ]]; then
+          # Reruns keep the original event's labels, so query the current decision.
+          # Only an exact boolean response can enable the maintainer override.
+          lookup_ok=false
+          for attempt in 1 2 3; do
+            if result="$(gh pr view "$PR_NUMBER" --json labels --jq '.labels | any(.name == "ci: lychee-non-blocking")')"; then
+              case "$result" in
+                true|false) allow_429="$result"; lookup_ok=true; break ;;
+              esac
+            fi
+            if (( attempt < 3 )); then
+              sleep $((attempt * 5))
+            fi
+          done
+          if [[ "$lookup_ok" != true ]]; then
+            echo "::warning::Could not read a valid PR label decision; using the default link policy. Rerun to apply ci: lychee-non-blocking."
+          elif [[ "$allow_429" == true ]]; then
+            echo "::notice::ci: lychee-non-blocking permits only HTTP 429 failures after retries."
+          fi
+        fi
+        echo "allow-429=$allow_429" >> "$GITHUB_OUTPUT"
+
     - name: Describe the link cache
       id: cache
       shell: bash --noprofile --norc -euo pipefail {0}
@@ -58,7 +97,7 @@ runs:
       shell: bash --noprofile --norc -euo pipefail {0}
       env:
         KIND: ${{ inputs.kind }}
-        POLICY: ${{ inputs.policy }}
+        POLICY: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'allow-429' || inputs.policy }}
         GITHUB_TOKEN: ${{ github.token }}
       run: |
         # Install into the interpreter that runs the driver, whatever shell

.github/workflows/build-docs.yml

@@ -295,28 +295,14 @@ jobs:
         with:
           python-version: "3.14"
 
-      # Full CI runs on a pull-request/N mirror. Use its PR number to query
-      # current labels, including when rerunning an older workflow attempt.
-      - name: Read the PR's Lychee rate-limit override
-        if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
-        id: lychee-policy
-        env:
-          GH_TOKEN: ${{ github.token }}
-          GH_REPO: ${{ github.repository }}
-        run: |
-          allow_429="$(gh pr view "$PR_NUMBER" --json labels --jq '.labels | any(.name == "ci: lychee-non-blocking")')"
-          echo "allow-429=$allow_429" >> "$GITHUB_OUTPUT"
-          if [[ "$allow_429" == true ]]; then
-            echo "::notice::ci: lychee-non-blocking permits only HTTP 429 failures after retries."
-          fi
-
       - name: Check rendered documentation links through pre-commit
         if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
         timeout-minutes: 60
         uses: ./.github/actions/lychee-links
         with:
           kind: rendered
-          policy: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'allow-429' || 'check' }}
+          # Full CI's pull-request/N mirror supplies the PR number.
+          pr-number: ${{ env.PR_NUMBER }}
 
       - name: Upload docs GitHub Pages artifact
         if: ${{ inputs.deploy-docs }}

.github/workflows/pre-commit.yml

@@ -140,22 +140,6 @@ jobs:
           LYCHEE_SMOKE_DIR: ${{ steps.lychee-smoke.outputs.directory }}
         run: python ci/tools/smoke_test_lychee_precommit.py --cleanup "$LYCHEE_SMOKE_DIR"
 
-      # Query current labels so applying or removing the override takes effect
-      # on a rerun, which otherwise keeps the original event's label snapshot.
-      - name: Read the PR's Lychee rate-limit override
-        if: github.event_name == 'pull_request'
-        id: lychee-policy
-        env:
-          GH_TOKEN: ${{ github.token }}
-          GH_REPO: ${{ github.repository }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          allow_429="$(gh pr view "$PR_NUMBER" --json labels --jq '.labels | any(.name == "ci: lychee-non-blocking")')"
-          echo "allow-429=$allow_429" >> "$GITHUB_OUTPUT"
-          if [[ "$allow_429" == true ]]; then
-            echo "::notice::ci: lychee-non-blocking permits only HTTP 429 failures after retries."
-          fi
-
       # Warm only Lychee from the shared nightly baseline, retaining successful
       # checks between up to three attempts. The full suite below runs once:
       # formatter changes must remain failures. A missing baseline is supported;
@@ -166,17 +150,18 @@ jobs:
         uses: ./.github/actions/lychee-links
         with:
           kind: authored
-          policy: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'allow-429' || 'cache-warm' }}
+          policy: cache-warm
+          pr-number: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || '' }}
 
       - name: Run pre-commit
         # Run the remaining hooks even if the override's link gate fails.
         # That earlier failure still makes the job fail.
-        if: ${{ !cancelled() && (success() || (steps.lychee-policy.outputs.allow-429 == 'true' && steps.lychee-check.outcome == 'failure')) }}
+        if: ${{ !cancelled() && (success() || (steps.lychee-check.outputs.allow-429 == 'true' && steps.lychee-check.outcome == 'failure')) }}
         env:
           GITHUB_TOKEN: ${{ github.token }}
           # The override uses the reported link result above. All other hooks
           # still run once; normal runs also invoke Lychee in the full suite.
-          SKIP: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'check-precommit-installed,lychee' || 'check-precommit-installed' }}
+          SKIP: ${{ steps.lychee-check.outputs.allow-429 == 'true' && 'check-precommit-installed,lychee' || 'check-precommit-installed' }}
         run: pre-commit run --all-files --show-diff-on-failure
 
       - name: Save pre-commit cache

ci/README.md

@@ -57,8 +57,14 @@ suite skips its duplicate Lychee invocation. Every other hook still runs once.
 When rate limiting persists, maintainers can apply `ci: lychee-non-blocking`
 to the PR and rerun the affected Linux/Windows pre-commit jobs or rendered
 documentation job. Applying or removing the label does not itself start a
-new workflow run. Each job queries the PR's current labels, so a rerun sees
-the current decision rather than the original event's label snapshot.
+new workflow run. The shared link-check action queries the PR's current labels,
+so a rerun sees the current decision rather than the original event's snapshot.
+The lookup makes up to three attempts, waiting 5 and 10 seconds between them.
+If every attempt fails or returns an invalid response, the action warns and
+keeps the caller's default policy without enabling the override: authored
+checks remain strict in the full pre-commit suite, and rendered checks keep
+their allowance for at most ten distinct HTTP 429 URLs. Rerun the affected job
+to retry the lookup and apply the label; other pre-commit hooks still run.
 
 The label selects the driver's `allow-429` policy for both authored and
 rendered checks. Lychee still runs and retries normally; only a final report
@@ -69,8 +75,8 @@ Successful checks retain their usual cache behavior; failures are never cached.
 
 Any other failure still blocks, including a mixture of HTTP 429s and other
 errors, broken local files or fragments, timeouts, and HTTP 403, 404, or 5xx
-responses. Hook setup, invalid or missing reports, failed label lookups, and
-the offline smoke checks remain blocking. Other exceptional failures require
+responses. Hook setup, invalid or missing reports, and the offline smoke
+checks remain blocking. Other exceptional failures require
 the normal admin-merge decision.
 
 The label applies only to PR checks. Local pre-commit runs, default-branch