|
| 1 | +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 2 | +# |
| 3 | +# SPDX-License-Identifier: Apache-2.0 |
| 4 | + |
| 5 | +name: Check documentation links |
| 6 | +description: Run a configured Lychee pre-commit hook with the shared URL cache and retained reports |
| 7 | + |
| 8 | +inputs: |
| 9 | + kind: |
| 10 | + description: "Which hook to run: authored or rendered" |
| 11 | + required: true |
| 12 | + policy: |
| 13 | + description: >- |
| 14 | + check accepts up to 10 rate-limited URLs; cache-warm warns for any unresolved |
| 15 | + link; allow-429 accepts only HTTP 429 failures under the maintainer override |
| 16 | + default: check |
| 17 | + refresh: |
| 18 | + description: "Check links afresh and publish the successful results as the new baseline" |
| 19 | + default: "false" |
| 20 | + pr-number: |
| 21 | + description: "PR whose current maintainer override label should be read; empty skips the lookup" |
| 22 | + default: "" |
| 23 | + |
| 24 | +outputs: |
| 25 | + allow-429: |
| 26 | + description: "Whether the current PR label explicitly enables the HTTP 429 override" |
| 27 | + value: ${{ steps.lychee-policy.outputs.allow-429 }} |
| 28 | + |
| 29 | +# Callers provide Python and the checked-out repository; the build of any |
| 30 | +# rendered documentation must already be complete. |
| 31 | +runs: |
| 32 | + using: composite |
| 33 | + steps: |
| 34 | + - name: Read the PR's Lychee rate-limit override |
| 35 | + id: lychee-policy |
| 36 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 37 | + env: |
| 38 | + GH_TOKEN: ${{ github.token }} |
| 39 | + GH_REPO: ${{ github.repository }} |
| 40 | + PR_NUMBER: ${{ inputs.pr-number }} |
| 41 | + run: | |
| 42 | + allow_429=false |
| 43 | + if [[ -n "$PR_NUMBER" ]]; then |
| 44 | + # Reruns keep the original event's labels, so query the current decision. |
| 45 | + # Only an exact boolean response can enable the maintainer override. |
| 46 | + lookup_ok=false |
| 47 | + for attempt in 1 2 3; do |
| 48 | + if result="$(gh pr view "$PR_NUMBER" --json labels --jq '.labels | any(.name == "ci: lychee-non-blocking")')"; then |
| 49 | + case "$result" in |
| 50 | + true|false) allow_429="$result"; lookup_ok=true; break ;; |
| 51 | + esac |
| 52 | + fi |
| 53 | + if (( attempt < 3 )); then |
| 54 | + sleep $((attempt * 5)) |
| 55 | + fi |
| 56 | + done |
| 57 | + if [[ "$lookup_ok" != true ]]; then |
| 58 | + echo "::warning::Could not read a valid PR label decision; using the default link policy. Rerun to apply ci: lychee-non-blocking." |
| 59 | + elif [[ "$allow_429" == true ]]; then |
| 60 | + echo "::notice::ci: lychee-non-blocking permits only HTTP 429 failures after retries." |
| 61 | + fi |
| 62 | + fi |
| 63 | + echo "allow-429=$allow_429" >> "$GITHUB_OUTPUT" |
| 64 | +
|
| 65 | + - name: Describe the link cache |
| 66 | + id: cache |
| 67 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 68 | + env: |
| 69 | + KIND: ${{ inputs.kind }} |
| 70 | + # Anything that can change a check result or the cache's meaning. The |
| 71 | + # hook configuration carries the native wheel pin and every hook option. |
| 72 | + POLICY_HASH: ${{ hashFiles('.pre-commit-config.yaml', 'lychee.toml', 'ci/tools/run_lychee.py', 'ci/tools/run_lychee_precommit.py', 'ci/tools/retry_lychee.py', 'ci/tools/checkout_source_links.py') }} |
| 73 | + run: | |
| 74 | + # Authored and rendered results stay apart: only rendered checks validate |
| 75 | + # fragments, and Lychee's cache does not record which validation ran. |
| 76 | + case "${KIND}" in |
| 77 | + authored) path=.lycheecache ;; |
| 78 | + rendered) path=.lychee-rendered/.lycheecache ;; |
| 79 | + *) echo "::error::Unknown link-check kind: ${KIND}"; exit 1 ;; |
| 80 | + esac |
| 81 | + prefix="lychee-v1-${KIND}-${POLICY_HASH}-baseline-" |
| 82 | + echo "path=${path}" >> "${GITHUB_OUTPUT}" |
| 83 | + echo "prefix=${prefix}" >> "${GITHUB_OUTPUT}" |
| 84 | + echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}" |
| 85 | +
|
| 86 | + - name: Restore successful link checks |
| 87 | + id: cache-restore |
| 88 | + # Refresh mode deliberately skips earlier URL results. |
| 89 | + if: ${{ inputs.refresh != 'true' }} |
| 90 | + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 |
| 91 | + with: |
| 92 | + path: ${{ steps.cache.outputs.path }} |
| 93 | + key: ${{ steps.cache.outputs.key }} |
| 94 | + restore-keys: ${{ steps.cache.outputs.prefix }} |
| 95 | + enableCrossOsArchive: true |
| 96 | + |
| 97 | + - name: Explain a missing shared Lychee cache |
| 98 | + # Prefix restores are normal; cache-hit only identifies exact key matches. |
| 99 | + if: ${{ inputs.refresh != 'true' && steps.cache-restore.outputs.cache-matched-key == '' }} |
| 100 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 101 | + env: |
| 102 | + KIND: ${{ inputs.kind }} |
| 103 | + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} |
| 104 | + WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/workflows/lychee.yml |
| 105 | + run: | |
| 106 | + 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." |
| 107 | + context="This is expected after checker changes in a PR; a refresh on ${DEFAULT_BRANCH} cannot seed settings that exist only in a PR." |
| 108 | + 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." |
| 109 | + echo "::notice title=Lychee ${KIND} cache::${message} ${context} ${hint} ${WORKFLOW_URL}" |
| 110 | + { |
| 111 | + printf '### Lychee %s cache\n\n' "$KIND" |
| 112 | + printf '%s\n\n%s\n\n%s\n\n' "$message" "$context" "$hint" |
| 113 | + printf '[Open the cache refresh workflow](%s).\n' "$WORKFLOW_URL" |
| 114 | + } >> "$GITHUB_STEP_SUMMARY" |
| 115 | +
|
| 116 | + - name: Harden pip |
| 117 | + uses: ./.github/actions/harden-pip |
| 118 | + |
| 119 | + - name: Check links through the configured pre-commit hook |
| 120 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 121 | + env: |
| 122 | + KIND: ${{ inputs.kind }} |
| 123 | + POLICY: ${{ steps.lychee-policy.outputs.allow-429 == 'true' && 'allow-429' || inputs.policy }} |
| 124 | + GITHUB_TOKEN: ${{ github.token }} |
| 125 | + run: | |
| 126 | + # Install into the interpreter that runs the driver, whatever shell |
| 127 | + # profile the caller's other steps use. |
| 128 | + python -m pip install pre-commit |
| 129 | + python ci/tools/run_lychee_precommit.py "${KIND}" --policy "${POLICY}" --max-attempts 3 \ |
| 130 | + --report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json" |
| 131 | +
|
| 132 | + - name: Publish fresh successful link checks |
| 133 | + # Only refresh runs publish, so every pull request restores the same |
| 134 | + # baseline. Saving keeps original timestamps and never caches failures. |
| 135 | + if: ${{ !cancelled() && inputs.refresh == 'true' }} |
| 136 | + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 |
| 137 | + with: |
| 138 | + path: ${{ steps.cache.outputs.path }} |
| 139 | + key: ${{ steps.cache.outputs.key }} |
| 140 | + enableCrossOsArchive: true |
| 141 | + |
| 142 | + - name: Upload link-check reports |
| 143 | + if: ${{ always() }} |
| 144 | + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 |
| 145 | + with: |
| 146 | + name: lychee-${{ inputs.kind }}-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }} |
| 147 | + path: ${{ runner.temp }}/lychee-reports/ |
| 148 | + if-no-files-found: ignore |
| 149 | + retention-days: 7 |
0 commit comments