From 4d51c2a61ee7e692540731d1cf7afa99581f59d0 Mon Sep 17 00:00:00 2001
From: manuka rahul <96047526+rahulpinto19@users.noreply.github.com>
Date: Wed, 18 Feb 2026 13:36:02 +0530
Subject: [PATCH] docs: optimize link checker (#2482)
Previous Functionality
The original workflow was designed to execute the link checker across
every file in the repository during each run.
Planned Enhancements
To improve efficiency, the process will be bifurcated into three
distinct components:
- Presubmit Check: The link checker will only target files that have
been modified.
- Improved Reporting: Broken links are now reported via a single,
automated comment in the PR conversation (which updates automatically on
subsequent pushes).
- Cleaner Logs: Suppressed non-critical redirect warnings and PR comment
now focuses strictly on broken URLs to make debugging faster.
---------
Co-authored-by: Twisha Bansal <58483338+twishabansal@users.noreply.github.com>
---
.github/workflows/link_checker_workflow.yaml | 86 +++++++++++++++++---
1 file changed, 75 insertions(+), 11 deletions(-)
diff --git a/.github/workflows/link_checker_workflow.yaml b/.github/workflows/link_checker_workflow.yaml
index 591221d16e0..c711227929a 100644
--- a/.github/workflows/link_checker_workflow.yaml
+++ b/.github/workflows/link_checker_workflow.yaml
@@ -15,6 +15,10 @@ name: Link Checker
on:
pull_request:
+permissions:
+ contents: read
+ pull-requests: write
+ issues: write
jobs:
@@ -23,8 +27,36 @@ jobs:
steps:
- name: Checkout Repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+ with:
+ fetch-depth: 0
+ - name: Identify Changed Files
+ id: changed-files
+ shell: bash
+ run: |
+ git fetch origin main
+ CHANGED_FILES=$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD)
+
+ if [ -z "$CHANGED_FILES" ]; then
+ echo "No markdown files changed. Skipping checks."
+ echo "HAS_CHANGES=false" >> $GITHUB_ENV
+ else
+ echo "--- Changed Files to Scan ---"
+ echo "$CHANGED_FILES"
+ echo "-----------------------------"
+
+ # FIX: Wrap filenames in quotes to handle spaces
+ FILES_QUOTED=$(echo "$CHANGED_FILES" | sed 's/^/"/;s/$/"/' | tr '\n' ' ')
+
+ # Write to env using EOF pattern
+ echo "CHECK_FILES<> $GITHUB_ENV
+ echo "$FILES_QUOTED" >> $GITHUB_ENV
+ echo "EOF" >> $GITHUB_ENV
+ echo "HAS_CHANGES=true" >> $GITHUB_ENV
+ fi
+
- name: Restore lychee cache
+ if: env.HAS_CHANGES == 'true'
uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
with:
path: .lycheecache
@@ -33,6 +65,7 @@ jobs:
- name: Link Checker
id: lychee-check
+ if: env.HAS_CHANGES == 'true'
uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2
continue-on-error: true
with:
@@ -42,8 +75,7 @@ jobs:
--cache
--max-cache-age 1d
--exclude '^neo4j\+.*' --exclude '^bolt://.*'
- README.md
- docs/
+ ${{ env.CHECK_FILES }}
output: lychee-report.md
format: markdown
fail: true
@@ -51,18 +83,50 @@ jobs:
debug: false
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ - name: Find comment
+ uses: peter-evans/find-comment@v4
+ id: find-comment
+ with:
+ issue-number: ${{ github.event.pull_request.number }}
+ comment-author: 'github-actions[bot]'
+ body-includes: "## Link Resolution Note"
+
+ - name: Delete comment on success
+ if: steps.lychee-check.outcome == 'success' && steps.find-comment.outputs.comment-id != ''
+ run: |
+ gh api \
+ --method DELETE \
+ -H "Accept: application/vnd.github+json" \
+ /repos/${{ github.repository }}/issues/comments/${{ steps.find-comment.outputs.comment-id }}
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Prepare Report
+ if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'
+ run: |
+ echo "## Link Resolution Note" > full-report.md
+
+
+ echo "Local links and directory changes work differently on GitHub than on the docsite.You must ensure fixes pass the **GitHub check** and also work with **\`hugo server\`**." >> full-report.md
+ echo "See [Link Checking and Fixing with Lychee](https://github.com/googleapis/genai-toolbox/blob/main/DEVELOPER.md#link-checking-and-fixing-with-lychee) for more details." >> full-report.md
+ echo "" >> full-report.md
+ sed -E '/(Redirect|Redirects per input)/d' lychee-report.md >> full-report.md
+
+ - name: Create PR Comment
+ if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'
+ uses: peter-evans/create-or-update-comment@v4
+ with:
+ comment-id: ${{ steps.find-comment.outputs.comment-id }}
+ issue-number: ${{ github.event.pull_request.number }}
+ body-path: full-report.md
+ edit-mode: replace
- name: Display Failure Report
# Run this ONLY if the link checker failed
if: steps.lychee-check.outcome == 'failure'
run: |
- echo "## Link Resolution Note" >> $GITHUB_STEP_SUMMARY
- echo "Local links and directory changes work differently on GitHub than on the docsite." >> $GITHUB_STEP_SUMMARY
- echo "You must ensure fixes pass the **GitHub check** and also work with **\`hugo server\`**." >> $GITHUB_STEP_SUMMARY
- echo "See [Link Checking and Fixing with Lychee](https://github.com/googleapis/genai-toolbox/blob/main/DEVELOPER.md#link-checking-and-fixing-with-lychee) for more details." >> $GITHUB_STEP_SUMMARY
- echo "---" >> $GITHUB_STEP_SUMMARY
-
- echo "### Broken Links Found" >> $GITHUB_STEP_SUMMARY
- cat ./lychee-report.md >> $GITHUB_STEP_SUMMARY
-
+ # We can now simply output the prepared file to the job summary
+ cat full-report.md >> $GITHUB_STEP_SUMMARY
+
+ # Fail the job
exit 1