|
| 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: "check accepts up to 10 rate-limited URLs; cache-warm reports every unresolved link as a warning" |
| 14 | + default: check |
| 15 | + refresh: |
| 16 | + description: "Check links afresh and publish the successful results as the new baseline" |
| 17 | + default: "false" |
| 18 | + |
| 19 | +# Callers provide Python and the checked-out repository; the build of any |
| 20 | +# rendered documentation must already be complete. |
| 21 | +runs: |
| 22 | + using: composite |
| 23 | + steps: |
| 24 | + - name: Describe the link cache |
| 25 | + id: cache |
| 26 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 27 | + env: |
| 28 | + KIND: ${{ inputs.kind }} |
| 29 | + # Anything that can change a check result or the cache's meaning. The |
| 30 | + # hook configuration carries the native wheel pin and every hook option. |
| 31 | + 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') }} |
| 32 | + run: | |
| 33 | + # Authored and rendered results stay apart: only rendered checks validate |
| 34 | + # fragments, and Lychee's cache does not record which validation ran. |
| 35 | + case "${KIND}" in |
| 36 | + authored) path=.lycheecache ;; |
| 37 | + rendered) path=.lychee-rendered/.lycheecache ;; |
| 38 | + *) echo "::error::Unknown link-check kind: ${KIND}"; exit 1 ;; |
| 39 | + esac |
| 40 | + prefix="lychee-v1-${KIND}-${POLICY_HASH}-baseline-" |
| 41 | + echo "path=${path}" >> "${GITHUB_OUTPUT}" |
| 42 | + echo "prefix=${prefix}" >> "${GITHUB_OUTPUT}" |
| 43 | + echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}" |
| 44 | +
|
| 45 | + - name: Restore successful link checks |
| 46 | + # Refresh mode deliberately skips earlier URL results. |
| 47 | + if: ${{ inputs.refresh != 'true' }} |
| 48 | + uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 |
| 49 | + with: |
| 50 | + path: ${{ steps.cache.outputs.path }} |
| 51 | + key: ${{ steps.cache.outputs.key }} |
| 52 | + restore-keys: ${{ steps.cache.outputs.prefix }} |
| 53 | + enableCrossOsArchive: true |
| 54 | + |
| 55 | + - name: Check links through the configured pre-commit hook |
| 56 | + shell: bash --noprofile --norc -euo pipefail {0} |
| 57 | + env: |
| 58 | + KIND: ${{ inputs.kind }} |
| 59 | + POLICY: ${{ inputs.policy }} |
| 60 | + GITHUB_TOKEN: ${{ github.token }} |
| 61 | + run: | |
| 62 | + # Install into the interpreter that runs the driver, whatever shell |
| 63 | + # profile the caller's other steps use. |
| 64 | + python -m pip install pre-commit |
| 65 | + python ci/tools/run_lychee_precommit.py "${KIND}" --policy "${POLICY}" --max-attempts 3 \ |
| 66 | + --report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json" |
| 67 | +
|
| 68 | + - name: Publish fresh successful link checks |
| 69 | + # Only nightly refreshes publish, so every pull request restores the same |
| 70 | + # baseline. Saving keeps original timestamps and never caches failures. |
| 71 | + if: ${{ !cancelled() && inputs.refresh == 'true' }} |
| 72 | + uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 |
| 73 | + with: |
| 74 | + path: ${{ steps.cache.outputs.path }} |
| 75 | + key: ${{ steps.cache.outputs.key }} |
| 76 | + enableCrossOsArchive: true |
| 77 | + |
| 78 | + - name: Upload link-check reports |
| 79 | + if: ${{ always() }} |
| 80 | + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 |
| 81 | + with: |
| 82 | + name: lychee-${{ inputs.kind }}-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }} |
| 83 | + path: ${{ runner.temp }}/lychee-reports/ |
| 84 | + if-no-files-found: ignore |
| 85 | + retention-days: 7 |
0 commit comments