|
| 1 | +# Monthly external-link check. |
| 2 | +# |
| 3 | +# The per-push CI (jekyll.yml) checks internal links only via |
| 4 | +# _bin/check_links.rb; this workflow covers external link rot, which is |
| 5 | +# too slow and too flaky to gate every push on. It builds the site, |
| 6 | +# runs lychee against the rendered HTML (excluding our own domain), and |
| 7 | +# opens a new GitHub issue with the report when broken links are found. |
| 8 | +# |
| 9 | +# 403/429 responses (and LinkedIn's proprietary 999) are accepted as |
| 10 | +# "alive": bot-walled sites (DOI resolvers, Medium, news sites) return |
| 11 | +# them to any checker, and a 403 can't distinguish a bot-wall from real |
| 12 | +# rot anyway. The genuine rot signal is 404/410/5xx/timeouts/TLS |
| 13 | +# failures. Verified 2026-07 by retesting every 403 with a browser |
| 14 | +# user-agent: all resolved to live publisher pages before refusing the |
| 15 | +# bot. The .lycheecache means a URL verified good is not re-checked for |
| 16 | +# 30 days, so transient failures do not repeat month to month. |
| 17 | +# |
| 18 | +# at:// URIs (standard.site link tags) cause lychee parse errors |
| 19 | +# because the scheme is not HTTP. Lychee has no way to suppress |
| 20 | +# pre-parse failures, so the report is filtered after the run. |
| 21 | +name: External Link Check |
| 22 | + |
| 23 | +on: |
| 24 | + schedule: |
| 25 | + # 08:14 UTC on the 3rd of each month. Odd minute to avoid the |
| 26 | + # top-of-hour scheduled-workflow congestion on GitHub's runners. |
| 27 | + - cron: "14 8 3 * *" |
| 28 | + workflow_dispatch: |
| 29 | + |
| 30 | +permissions: |
| 31 | + contents: read |
| 32 | + issues: write |
| 33 | + |
| 34 | +jobs: |
| 35 | + link-check: |
| 36 | + runs-on: ubuntu-latest |
| 37 | + steps: |
| 38 | + - name: Checkout |
| 39 | + uses: actions/checkout@v7 |
| 40 | + |
| 41 | + - name: Setup Ruby |
| 42 | + uses: ruby/setup-ruby@v1 |
| 43 | + with: |
| 44 | + bundler-cache: true |
| 45 | + cache-version: 0 |
| 46 | + |
| 47 | + - name: Build with Jekyll |
| 48 | + run: bundle exec jekyll build |
| 49 | + env: |
| 50 | + JEKYLL_ENV: production |
| 51 | + |
| 52 | + - name: Restore lychee cache |
| 53 | + uses: actions/cache@v4 |
| 54 | + with: |
| 55 | + path: .lycheecache |
| 56 | + key: cache-lychee-${{ github.sha }} |
| 57 | + restore-keys: cache-lychee- |
| 58 | + |
| 59 | + - name: Check external links |
| 60 | + id: lychee |
| 61 | + uses: lycheeverse/lychee-action@v2 |
| 62 | + with: |
| 63 | + args: >- |
| 64 | + --no-progress |
| 65 | + --include-mail |
| 66 | + --cache |
| 67 | + --max-cache-age 30d |
| 68 | + --root-dir "${{ github.workspace }}/_site" |
| 69 | + --exclude '^https?://(www\.)?alexgude\.com' |
| 70 | + --accept '200..=299, 403, 429, 999' |
| 71 | + --max-concurrency 32 |
| 72 | + --timeout 20 |
| 73 | + --max-retries 2 |
| 74 | + '_site/**/*.html' |
| 75 | + fail: false |
| 76 | + |
| 77 | + - name: Filter at:// parse errors from report |
| 78 | + if: steps.lychee.outputs.exit_code != 0 |
| 79 | + run: | |
| 80 | + grep -v "Cannot parse 'at://" ./lychee/out.md > ./lychee/filtered.md || true |
| 81 | + if grep -qE '^\[ERROR\]|^\[TIMEOUT\]|^\[[0-9]{3}\]' ./lychee/filtered.md; then |
| 82 | + echo "has_errors=true" >> "$GITHUB_OUTPUT" |
| 83 | + fi |
| 84 | + mv ./lychee/filtered.md ./lychee/out.md |
| 85 | + id: filter |
| 86 | + |
| 87 | + - name: Get report month |
| 88 | + if: steps.filter.outputs.has_errors == 'true' |
| 89 | + id: date |
| 90 | + run: echo "month=$(date -u +%Y-%m)" >> "$GITHUB_OUTPUT" |
| 91 | + |
| 92 | + - name: Open issue with report |
| 93 | + if: steps.filter.outputs.has_errors == 'true' |
| 94 | + uses: peter-evans/create-issue-from-file@v5 |
| 95 | + with: |
| 96 | + title: "Broken external links — ${{ steps.date.outputs.month }}" |
| 97 | + content-filepath: ./lychee/out.md |
| 98 | + |
| 99 | + - name: Fail run if links are broken |
| 100 | + if: steps.filter.outputs.has_errors == 'true' |
| 101 | + run: exit 1 |
0 commit comments