🔧 Infra · 🌙 Link Rot (Nightly) #147
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: '🔧 Infra · 🌙 Link Rot (Nightly)' | |
| # ============================================================================= | |
| # 🌙 Link Rot — Nightly Lychee sweep with sticky-issue reporter (Tier 3) | |
| # ============================================================================= | |
| # | |
| # Tier 1 (pre-commit) catches new internal-link breakage before it lands. | |
| # Tier 2 (per-site validate-dev) catches external breakage at PR/push time. | |
| # Tier 3 (this workflow) is the long-tail: nightly cron sweep across every | |
| # subsite, with results aggregated into a single sticky GitHub issue so the | |
| # team has one durable list of broken URLs to triage. | |
| # | |
| # Why a sticky issue: | |
| # - One source of truth instead of 100 closed-then-reopened issues. | |
| # - Body is rewritten each run with the current broken-link inventory. | |
| # - Comments preserve trend (week-over-week count delta). | |
| # | |
| # Trigger: | |
| # - schedule: 04:30 UTC daily (low-traffic window, after EU bedtime). | |
| # - workflow_dispatch: manual one-off. | |
| # | |
| # Issue label: link-rot | |
| # Issue title: 🔗 Link Rot Tracker (auto-updated nightly) | |
| # | |
| # ============================================================================= | |
| on: | |
| schedule: | |
| - cron: '30 4 * * *' # 04:30 UTC daily | |
| workflow_dispatch: | |
| inputs: | |
| dry_run: | |
| description: 'Skip issue update (just print results to job log)' | |
| required: false | |
| type: boolean | |
| default: false | |
| permissions: | |
| contents: read | |
| issues: write | |
| concurrency: | |
| group: link-rot-nightly | |
| cancel-in-progress: false | |
| jobs: | |
| # ============================================================================= | |
| # Sweep each site in parallel via the reusable Lychee workflow. | |
| # We deliberately reuse infra-link-check.yml so any tweak to Lychee args / | |
| # ignore-file handling stays in one place. | |
| # ============================================================================= | |
| sweep-book: | |
| name: '📚 Sweep · Book' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './book/quarto/contents/**/*.qmd' | |
| lycheeignore_path: 'book/config/linting/.lycheeignore' | |
| max_concurrency: 12 | |
| fail_on_broken: false | |
| sweep-kits: | |
| name: '📦 Sweep · Kits' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './kits/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-labs: | |
| name: '🔮 Sweep · Labs' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './labs/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-mlsysim: | |
| name: '🧮 Sweep · MLSys·im' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './mlsysim/docs/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-slides: | |
| name: '📊 Sweep · Slides' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './slides/**/*.{qmd,md}' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-instructors: | |
| name: '🎓 Sweep · Instructors' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './instructors/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 5 | |
| fail_on_broken: false | |
| sweep-tinytorch: | |
| name: '🔥 Sweep · TinyTorch' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './tinytorch/quarto/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-site: | |
| name: '🌐 Sweep · Unified Site' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './site/**/*.qmd' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| sweep-staffml: | |
| name: '🎯 Sweep · StaffML' | |
| uses: ./.github/workflows/infra-link-check.yml | |
| with: | |
| path_pattern: './interviews/**/*.{md,mdx,qmd}' | |
| lycheeignore_path: 'shared/config/.lycheeignore-nightly' | |
| max_concurrency: 8 | |
| fail_on_broken: false | |
| # ============================================================================= | |
| # Aggregate sweep results and act on the tracker issue ONLY when there's | |
| # something to act on. Quiet success is the goal. | |
| # | |
| # Decision matrix: | |
| # | |
| # broken sites | tracker exists | action | |
| # ─────────────|────────────────|──────────────────────────────────────── | |
| # 0 | no | do nothing (silent green) | |
| # 0 | yes | close tracker with "all clear" comment | |
| # >0 | no | open tracker with full state + samples | |
| # >0 | yes | edit body; add comment ONLY if state changed | |
| # | |
| # State change = different broken-site set OR different total-count, so | |
| # routine "still broken, no news" runs don't spam comments. | |
| # ============================================================================= | |
| report: | |
| name: '📝 Triage link-rot tracker issue' | |
| runs-on: ubuntu-latest | |
| needs: | |
| - sweep-book | |
| - sweep-kits | |
| - sweep-labs | |
| - sweep-mlsysim | |
| - sweep-slides | |
| - sweep-instructors | |
| - sweep-tinytorch | |
| - sweep-site | |
| - sweep-staffml | |
| if: always() | |
| steps: | |
| - name: 📥 Checkout | |
| uses: actions/checkout@v6 | |
| # ------------------------------------------------------------------- | |
| # 1. Aggregate sweep outputs. We read `needs.<job>.outputs.check-status` | |
| # (the lychee verdict) NOT `needs.<job>.result` (the job result). | |
| # With continue-on-error on the lychee step, the job result is | |
| # always "success" — only the output reflects link health. | |
| # ------------------------------------------------------------------- | |
| - name: 🧮 Aggregate sweep results | |
| id: aggregate | |
| env: | |
| # Each pair: status output from the reusable workflow. | |
| STATUS_BOOK: ${{ needs.sweep-book.outputs.check-status }} | |
| STATUS_KITS: ${{ needs.sweep-kits.outputs.check-status }} | |
| STATUS_LABS: ${{ needs.sweep-labs.outputs.check-status }} | |
| STATUS_MLSYSIM: ${{ needs.sweep-mlsysim.outputs.check-status }} | |
| STATUS_SLIDES: ${{ needs.sweep-slides.outputs.check-status }} | |
| STATUS_INSTRUCTORS: ${{ needs.sweep-instructors.outputs.check-status }} | |
| STATUS_TINYTORCH: ${{ needs.sweep-tinytorch.outputs.check-status }} | |
| STATUS_SITE: ${{ needs.sweep-site.outputs.check-status }} | |
| STATUS_STAFFML: ${{ needs.sweep-staffml.outputs.check-status }} | |
| COUNT_BOOK: ${{ needs.sweep-book.outputs.broken-links-count }} | |
| COUNT_KITS: ${{ needs.sweep-kits.outputs.broken-links-count }} | |
| COUNT_LABS: ${{ needs.sweep-labs.outputs.broken-links-count }} | |
| COUNT_MLSYSIM: ${{ needs.sweep-mlsysim.outputs.broken-links-count }} | |
| COUNT_SLIDES: ${{ needs.sweep-slides.outputs.broken-links-count }} | |
| COUNT_INSTRUCTORS: ${{ needs.sweep-instructors.outputs.broken-links-count }} | |
| COUNT_TINYTORCH: ${{ needs.sweep-tinytorch.outputs.broken-links-count }} | |
| COUNT_SITE: ${{ needs.sweep-site.outputs.broken-links-count }} | |
| COUNT_STAFFML: ${{ needs.sweep-staffml.outputs.broken-links-count }} | |
| SAMPLE_BOOK: ${{ needs.sweep-book.outputs.broken-links-sample }} | |
| SAMPLE_KITS: ${{ needs.sweep-kits.outputs.broken-links-sample }} | |
| SAMPLE_LABS: ${{ needs.sweep-labs.outputs.broken-links-sample }} | |
| SAMPLE_MLSYSIM: ${{ needs.sweep-mlsysim.outputs.broken-links-sample }} | |
| SAMPLE_SLIDES: ${{ needs.sweep-slides.outputs.broken-links-sample }} | |
| SAMPLE_INSTRUCTORS: ${{ needs.sweep-instructors.outputs.broken-links-sample }} | |
| SAMPLE_TINYTORCH: ${{ needs.sweep-tinytorch.outputs.broken-links-sample }} | |
| SAMPLE_SITE: ${{ needs.sweep-site.outputs.broken-links-sample }} | |
| SAMPLE_STAFFML: ${{ needs.sweep-staffml.outputs.broken-links-sample }} | |
| # Job results in case the sweep itself died (infra issue, not link rot). | |
| RESULT_BOOK: ${{ needs.sweep-book.result }} | |
| RESULT_KITS: ${{ needs.sweep-kits.result }} | |
| RESULT_LABS: ${{ needs.sweep-labs.result }} | |
| RESULT_MLSYSIM: ${{ needs.sweep-mlsysim.result }} | |
| RESULT_SLIDES: ${{ needs.sweep-slides.result }} | |
| RESULT_INSTRUCTORS: ${{ needs.sweep-instructors.result }} | |
| RESULT_TINYTORCH: ${{ needs.sweep-tinytorch.result }} | |
| RESULT_SITE: ${{ needs.sweep-site.result }} | |
| RESULT_STAFFML: ${{ needs.sweep-staffml.result }} | |
| run: | | |
| set -euo pipefail | |
| NOW=$(date -u +"%Y-%m-%dT%H:%MZ") | |
| BODY_FILE=$(mktemp) | |
| # State-fingerprint = ordered list of "site:count" pairs for sites | |
| # with broken links. Used to decide whether to post a new comment. | |
| FINGERPRINT="" | |
| BROKEN_SITES=0 | |
| INFRA_FAIL=0 | |
| TOTAL_BROKEN=0 | |
| { | |
| echo "# 🔗 Link Rot Tracker" | |
| echo "" | |
| echo "_Auto-updated nightly. Last sweep: **$NOW**._" | |
| echo "" | |
| echo "This tracker is **only opened/updated when broken links are present**. When everything is clean, it is closed automatically — silence is success." | |
| echo "" | |
| echo "## Per-site status" | |
| echo "" | |
| echo "| Site | Status | Broken |" | |
| echo "|------|--------|-------:|" | |
| # Iterate sites by parallel arrays so we can also pull samples. | |
| sites=( | |
| "📚 Book|BOOK" | |
| "📦 Kits|KITS" | |
| "🔮 Labs|LABS" | |
| "🧮 MLSys·im|MLSYSIM" | |
| "📊 Slides|SLIDES" | |
| "🎓 Instructors|INSTRUCTORS" | |
| "🔥 TinyTorch|TINYTORCH" | |
| "🌐 Unified Site|SITE" | |
| "🎯 StaffML|STAFFML" | |
| ) | |
| for entry in "${sites[@]}"; do | |
| label="${entry%%|*}" | |
| key="${entry##*|}" | |
| status_var="STATUS_$key" | |
| count_var="COUNT_$key" | |
| result_var="RESULT_$key" | |
| status="${!status_var:-}" | |
| count="${!count_var:-}" | |
| result="${!result_var:-}" | |
| if [ "$result" != "success" ] && [ "$result" != "failure" ]; then | |
| # cancelled / skipped — sweep didn't run normally. | |
| icon="🛑"; label_status="$result (no sweep)"; INFRA_FAIL=$((INFRA_FAIL+1)) | |
| elif [ -z "$status" ]; then | |
| # Job ran but didn't produce an output — treat as infra blip. | |
| icon="❓"; label_status="no output"; INFRA_FAIL=$((INFRA_FAIL+1)) | |
| elif [ "$status" = "success" ]; then | |
| icon="✅"; label_status="clean"; count="0" | |
| else | |
| icon="❌"; label_status="broken" | |
| BROKEN_SITES=$((BROKEN_SITES+1)) | |
| # Numeric add only if we have a real number. | |
| if [[ "$count" =~ ^[0-9]+$ ]]; then | |
| TOTAL_BROKEN=$((TOTAL_BROKEN + count)) | |
| FINGERPRINT="${FINGERPRINT}${key}:${count};" | |
| else | |
| FINGERPRINT="${FINGERPRINT}${key}:?;" | |
| fi | |
| fi | |
| echo "| $label | $icon $label_status | ${count:-—} |" | |
| done | |
| echo "" | |
| echo "**Sites with broken links: $BROKEN_SITES** · **Total broken URLs: $TOTAL_BROKEN**" | |
| if [ "$INFRA_FAIL" -gt 0 ]; then | |
| echo "" | |
| echo "> ⚠️ $INFRA_FAIL sweep(s) didn't run cleanly — verdict for those sites is unknown." | |
| fi | |
| # Per-site samples (only render sites that are broken). | |
| if [ "$BROKEN_SITES" -gt 0 ]; then | |
| echo "" | |
| echo "## First broken URLs by site" | |
| echo "" | |
| for entry in "${sites[@]}"; do | |
| label="${entry%%|*}" | |
| key="${entry##*|}" | |
| status_var="STATUS_$key" | |
| sample_var="SAMPLE_$key" | |
| status="${!status_var:-}" | |
| sample="${!sample_var:-}" | |
| [ "$status" = "failure" ] || continue | |
| [ -n "$sample" ] || continue | |
| echo "<details><summary><b>$label</b></summary>" | |
| echo "" | |
| while IFS= read -r url; do | |
| [ -z "$url" ] && continue | |
| echo "- \`$url\`" | |
| done <<< "$sample" | |
| echo "" | |
| echo "</details>" | |
| echo "" | |
| done | |
| fi | |
| echo "" | |
| echo "## Triage notes" | |
| echo "" | |
| echo "- Workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" | |
| echo "- To intentionally suppress a URL pattern: add it to \`shared/config/.lycheeignore\` (cross-site) or \`book/config/linting/.lycheeignore\` (book-only)." | |
| echo "- To re-trigger now: \`gh workflow run infra-link-rot-nightly.yml\`." | |
| echo "" | |
| echo "<!-- fingerprint: $FINGERPRINT -->" | |
| echo "<sub>Run id: ${{ github.run_id }}</sub>" | |
| } > "$BODY_FILE" | |
| echo "body_file=$BODY_FILE" >> "$GITHUB_OUTPUT" | |
| echo "broken_sites=$BROKEN_SITES" >> "$GITHUB_OUTPUT" | |
| echo "total_broken=$TOTAL_BROKEN" >> "$GITHUB_OUTPUT" | |
| echo "infra_fail=$INFRA_FAIL" >> "$GITHUB_OUTPUT" | |
| echo "fingerprint=$FINGERPRINT" >> "$GITHUB_OUTPUT" | |
| echo "" | |
| echo "===== Report Body (preview) =====" | |
| cat "$BODY_FILE" | |
| echo "=================================" | |
| - name: 🪟 Append step summary | |
| run: | | |
| { | |
| echo "## 🌙 Link Rot Sweep" | |
| echo "" | |
| echo "- Broken sites: **${{ steps.aggregate.outputs.broken_sites }}**" | |
| echo "- Total broken URLs: **${{ steps.aggregate.outputs.total_broken }}**" | |
| echo "- Infra failures: **${{ steps.aggregate.outputs.infra_fail }}**" | |
| echo "" | |
| cat "${{ steps.aggregate.outputs.body_file }}" | |
| } >> "$GITHUB_STEP_SUMMARY" | |
| # ------------------------------------------------------------------- | |
| # 2. Make sure the label exists. Cheap; harmless to keep on every run. | |
| # ------------------------------------------------------------------- | |
| - name: 🏷️ Ensure link-rot label exists | |
| if: ${{ inputs.dry_run != true }} | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| if ! gh label list --repo "${{ github.repository }}" --search link-rot --json name --jq '.[].name' | grep -qx 'link-rot'; then | |
| gh label create link-rot \ | |
| --repo "${{ github.repository }}" \ | |
| --description "Aggregated nightly link-rot tracker" \ | |
| --color "ededed" \ | |
| || echo "Label already exists or could not be created (non-fatal)." | |
| fi | |
| # ------------------------------------------------------------------- | |
| # 3. Triage the tracker issue per the decision matrix at top of file. | |
| # ------------------------------------------------------------------- | |
| - name: 🔁 Triage tracker issue | |
| if: ${{ inputs.dry_run != true }} | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| BODY_FILE: ${{ steps.aggregate.outputs.body_file }} | |
| BROKEN_SITES: ${{ steps.aggregate.outputs.broken_sites }} | |
| TOTAL_BROKEN: ${{ steps.aggregate.outputs.total_broken }} | |
| INFRA_FAIL: ${{ steps.aggregate.outputs.infra_fail }} | |
| FINGERPRINT: ${{ steps.aggregate.outputs.fingerprint }} | |
| run: | | |
| set -euo pipefail | |
| TITLE="🔗 Link Rot Tracker (auto-updated nightly)" | |
| RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" | |
| # Find an existing open tracker (by label + title prefix). | |
| ISSUE_NUM=$(gh issue list \ | |
| --repo "${{ github.repository }}" \ | |
| --state open \ | |
| --label link-rot \ | |
| --search "in:title \"Link Rot Tracker\"" \ | |
| --json number \ | |
| --jq '.[0].number // empty') | |
| # ---------- BRANCH A: nothing broken ---------- | |
| if [ "$BROKEN_SITES" -eq 0 ]; then | |
| if [ -z "$ISSUE_NUM" ]; then | |
| # Quiet green night. Don't open an issue. Don't comment. | |
| echo "::notice::All sites clean and no open tracker. No action taken (silent success)." | |
| exit 0 | |
| fi | |
| # An old tracker exists from a previous broken run; close it now. | |
| echo "All sites clean. Closing tracker #$ISSUE_NUM." | |
| ALL_CLEAR_BODY=$(printf '%s\n\n%s\n' \ | |
| "✅ All sites clean as of nightly sweep. Auto-closing this tracker." \ | |
| "Run: $RUN_URL") | |
| gh issue comment "$ISSUE_NUM" \ | |
| --repo "${{ github.repository }}" \ | |
| --body "$ALL_CLEAR_BODY" | |
| gh issue close "$ISSUE_NUM" \ | |
| --repo "${{ github.repository }}" \ | |
| --reason completed | |
| exit 0 | |
| fi | |
| # ---------- BRANCH B: at least one site has broken links ---------- | |
| if [ -z "$ISSUE_NUM" ]; then | |
| echo "Broken links detected and no open tracker. Creating new tracker." | |
| gh issue create \ | |
| --repo "${{ github.repository }}" \ | |
| --title "$TITLE" \ | |
| --label link-rot \ | |
| --body-file "$BODY_FILE" | |
| exit 0 | |
| fi | |
| # Tracker exists and we have new findings. Always refresh body so | |
| # the issue reflects current truth. Only post a comment if state | |
| # actually changed since the last sweep — silence when nothing's new. | |
| PREV_FP=$(gh issue view "$ISSUE_NUM" \ | |
| --repo "${{ github.repository }}" \ | |
| --json body \ | |
| --jq '.body' \ | |
| | grep -oE 'fingerprint: [^ ]*' \ | |
| | head -n1 \ | |
| | sed 's/fingerprint: //' || true) | |
| echo "Updating tracker #$ISSUE_NUM (prev fp='${PREV_FP:-<none>}', new fp='$FINGERPRINT')." | |
| gh issue edit "$ISSUE_NUM" \ | |
| --repo "${{ github.repository }}" \ | |
| --body-file "$BODY_FILE" | |
| if [ "$PREV_FP" != "$FINGERPRINT" ]; then | |
| echo "State changed — posting trend comment." | |
| gh issue comment "$ISSUE_NUM" \ | |
| --repo "${{ github.repository }}" \ | |
| --body "🔄 Link state changed: **$BROKEN_SITES site(s)**, **$TOTAL_BROKEN broken URL(s)**. See [run]($RUN_URL)." | |
| else | |
| echo "Same broken-link fingerprint as previous sweep — body refreshed, no comment posted." | |
| fi |