From ee60c9dfd9da3d51073e989382db992206804faa Mon Sep 17 00:00:00 2001
From: xianlubird <xianlubird@gmail.com>
Date: Thu, 6 Aug 2026 15:21:47 +0800
Subject: [PATCH 1/2] fix(ci): retry flaky documentation link checks

Signed-off-by: xianlubird <xianlubird@gmail.com>
---
 .github/workflows/docs-link-check.yml | 38 ++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml
index 5cb0a21370f8..8cc2df9a14e6 100644
--- a/.github/workflows/docs-link-check.yml
+++ b/.github/workflows/docs-link-check.yml
@@ -25,7 +25,43 @@ jobs:
           key: cache-lychee-${{ github.run_id }}
           restore-keys: cache-lychee-
 
-      - name: Check documentation links with lychee
+      - name: Check documentation links with lychee (first attempt)
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --cache
+            --no-progress
+            --max-retries 4
+            --retry-wait-time 3
+            --timeout 30
+            --root-dir ${{ github.workspace }}
+            --exclude-path ".*ATTRIBUTIONS.*"
+            --exclude-path "./lib/llm/tests/data/.*"
+            --exclude-path "./container/compliance/spdx_licenses/.*"
+            --accept "200..=299, 403, 429"
+            --exclude-all-private
+            --exclude 0.0.0.0
+            --verbose
+            --host-concurrency 10
+            --host-request-interval 1s
+            --host-stats
+            .
+          # Capture the exit code so the retry step can propagate a second failure.
+          fail: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Clear failed links from cache before retry
+        if: steps.lychee.outputs.exit_code != '0'
+        run: |
+          if [ -f .lycheecache ]; then
+            grep -E ',2[0-9]{2},' .lycheecache > .lycheecache.tmp || true
+            mv .lycheecache.tmp .lycheecache
+          fi
+
+      - name: Retry documentation links with lychee
+        if: steps.lychee.outputs.exit_code != '0'
         uses: lycheeverse/lychee-action@v2
         with:
           args: >-

From cb319b0d1be8ab0130db4c970004c89befa5f7b5 Mon Sep 17 00:00:00 2001
From: xianlubird <xianlubird@gmail.com>
Date: Fri, 7 Aug 2026 08:45:25 +0800
Subject: [PATCH 2/2] fix(ci): reuse lychee arguments for retry

Signed-off-by: xianlubird <xianlubird@gmail.com>
---
 .github/workflows/docs-link-check.yml | 31 +++++++--------------------
 1 file changed, 8 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml
index 8cc2df9a14e6..d14e5ab223e0 100644
--- a/.github/workflows/docs-link-check.yml
+++ b/.github/workflows/docs-link-check.yml
@@ -29,7 +29,7 @@ jobs:
         id: lychee
         uses: lycheeverse/lychee-action@v2
         with:
-          args: >-
+          args: &lychee_args >-
             --cache
             --no-progress
             --max-retries 4
@@ -56,7 +56,8 @@ jobs:
         if: steps.lychee.outputs.exit_code != '0'
         run: |
           if [ -f .lycheecache ]; then
-            grep -E ',2[0-9]{2},' .lycheecache > .lycheecache.tmp || true
+            awk -F',' '$(NF-1) ~ /^(2[0-9][0-9]|403|429)$/ { print }' \
+              .lycheecache > .lycheecache.tmp
             mv .lycheecache.tmp .lycheecache
           fi
 
@@ -64,24 +65,7 @@ jobs:
         if: steps.lychee.outputs.exit_code != '0'
         uses: lycheeverse/lychee-action@v2
         with:
-          args: >-
-            --cache
-            --no-progress
-            --max-retries 4
-            --retry-wait-time 3
-            --timeout 30
-            --root-dir ${{ github.workspace }}
-            --exclude-path ".*ATTRIBUTIONS.*"
-            --exclude-path "./lib/llm/tests/data/.*"
-            --exclude-path "./container/compliance/spdx_licenses/.*"
-            --accept "200..=299, 403, 429"
-            --exclude-all-private
-            --exclude 0.0.0.0
-            --verbose
-            --host-concurrency 10
-            --host-request-interval 1s
-            --host-stats
-            .
+          args: *lychee_args
           fail: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -90,13 +74,14 @@ jobs:
         if: always() && github.ref == 'refs/heads/main'
         run: |
           if [ -f .lycheecache ]; then
-            grep -E ',2[0-9]{2},' .lycheecache > .lycheecache.tmp || true
+            awk -F',' '$(NF-1) ~ /^(2[0-9][0-9]|403|429)$/ { print }' \
+              .lycheecache > .lycheecache.tmp
             cutoff=$(( $(date +%s) - 93600 ))
-            stale=$(awk -F',' -v c="$cutoff" '$3 < c' .lycheecache.tmp)
+            stale=$(awk -F',' -v c="$cutoff" '$NF < c' .lycheecache.tmp)
             if [ -n "$stale" ]; then
               echo "Removing stale cache entries (>26h old):"
               echo "$stale"
-              awk -F',' -v c="$cutoff" '$3 >= c' .lycheecache.tmp > .lycheecache.tmp2 || true
+              awk -F',' -v c="$cutoff" '$NF >= c' .lycheecache.tmp > .lycheecache.tmp2 || true
               mv .lycheecache.tmp2 .lycheecache.tmp
             fi
             mv .lycheecache.tmp .lycheecache