Link checker: find and fix broken doc links daily

1---2description: Daily automated link checker that finds and fixes broken links in documentation files

3on:4  schedule: daily on weekdays

5permissions: read-all6timeout-minutes: 607network:8  allowed:9    - node10    - python11    - github

12steps:13  - name: Checkout repository14    uses: actions/checkout@v415    with:16      fetch-depth: 017      persist-credentials: false1819  - name: Check and test all documentation links20    id: link-check21    run: |22      mkdir -p /tmp/gh-aw/agent23      echo "# Link Check Results" > /tmp/gh-aw/agent/link-check-results.md24      echo "" >> /tmp/gh-aw/agent/link-check-results.md25      26      # Find all markdown files in docs directory and README27      echo "Finding all markdown files..."28      MARKDOWN_FILES=$(find docs README.md -type f -name "*.md" 2>/dev/null || echo "")29      30      if [ -z "$MARKDOWN_FILES" ]; then31        echo "No markdown files found"32        echo "no_files=true" >> $GITHUB_OUTPUT33        exit 034      fi35      36      # Extract all links from markdown files37      echo "## Links Found" >> /tmp/gh-aw/agent/link-check-results.md38      echo "" >> /tmp/gh-aw/agent/link-check-results.md39      40      # Use grep to find markdown links and HTTP(S) URLs41      for file in $MARKDOWN_FILES; do42        echo "Checking $file..."43        # Extract markdown links [text](url)44        grep -oP '\[([^\]]+)\]\(([^\)]+)\)' "$file" | grep -oP '\(([^\)]+)\)' | tr -d '()' >> /tmp/gh-aw/agent/all-links.txt 2>/dev/null || true45        # Extract plain HTTP(S) URLs46        grep -oP 'https?://[^\s<>"]+' "$file" >> /tmp/gh-aw/agent/all-links.txt 2>/dev/null || true47      done48      49      # Remove duplicates and sort50      if [ -f /tmp/gh-aw/agent/all-links.txt ]; then51        sort -u /tmp/gh-aw/agent/all-links.txt > /tmp/gh-aw/agent/unique-links.txt52        LINK_COUNT=$(wc -l < /tmp/gh-aw/agent/unique-links.txt)53        echo "Found $LINK_COUNT unique links" >> /tmp/gh-aw/agent/link-check-results.md54        echo "" >> /tmp/gh-aw/agent/link-check-results.md55      else56        echo "No links found" >> /tmp/gh-aw/agent/link-check-results.md57        echo "no_links=true" >> $GITHUB_OUTPUT58        exit 059      fi60      61      # Test each link62      echo "## Link Test Results" >> /tmp/gh-aw/agent/link-check-results.md63      echo "" >> /tmp/gh-aw/agent/link-check-results.md64      echo "Testing links..." >> /tmp/gh-aw/agent/link-check-results.md65      66      BROKEN_COUNT=067      WORKING_COUNT=068      69      while IFS= read -r url; do70        # Skip relative links and anchors71        if [[ "$url" == "#"* ]] || [[ "$url" != "http"* ]]; then72          continue73        fi74        75        # Test the link with curl76        HTTP_CODE=$(curl -L -s -o /dev/null -w "%{http_code}" --max-time 10 "$url" 2>/dev/null || echo "000")77        78        if [[ "$HTTP_CODE" =~ ^2 ]] || [[ "$HTTP_CODE" =~ ^3 ]]; then79          WORKING_COUNT=$((WORKING_COUNT + 1))80          echo "✅ $url (HTTP $HTTP_CODE)" >> /tmp/gh-aw/agent/link-check-results.md81        else82          BROKEN_COUNT=$((BROKEN_COUNT + 1))83          echo "❌ $url (HTTP $HTTP_CODE)" >> /tmp/gh-aw/agent/link-check-results.md84        fi85      done < /tmp/gh-aw/agent/unique-links.txt86      87      echo "" >> /tmp/gh-aw/agent/link-check-results.md88      echo "**Summary:** $WORKING_COUNT working, $BROKEN_COUNT broken" >> /tmp/gh-aw/agent/link-check-results.md89      90      # Output results91      echo "broken_count=$BROKEN_COUNT" >> $GITHUB_OUTPUT92      echo "working_count=$WORKING_COUNT" >> $GITHUB_OUTPUT93      94      cat /tmp/gh-aw/agent/link-check-results.md95    shell: bash9697tools:98  github:99    toolsets: [default]100  cache-memory: true101  web-fetch:102

103safe-outputs:104  create-pull-request:105    title-prefix: "[link-checker] "106    labels: [documentation, automated]107    draft: false108    protected-files: fallback-to-issue109    if-no-changes: "warn"110  noop:111---112113# Daily Link Checker & Fixer114115You are an automated link checker and fixer agent. Your job is to find and fix broken links in the documentation files of this repository.116117## Your Mission118119Your workflow has already collected and tested all links in the previous step. Use the test results to identify broken links and fix them where possible.120121## Step 1: Review Link Check Results122123The link check step has already run and created a report at `/tmp/gh-aw/agent/link-check-results.md`. Read this file to see:124- All links found in the documentation125- Which links are working (✅) and which are broken (❌)126- HTTP status codes for each link127128Use bash to read the file:129~~~bash130cat /tmp/gh-aw/agent/link-check-results.md131~~~132133## Step 2: Load Cache Memory134135Check cache memory for previously identified unfixable broken links:136- Load the cache memory to see if there are any broken links we've tried to fix before but couldn't137- These are links that are permanently broken or removed from the internet138- Skip these links to avoid repeated attempts139140The cache memory should store a JSON object with this structure:141~~~json142{143  "unfixable_links": [144    {145      "url": "https://example.com/removed-page",146      "reason": "404 Not Found - content removed",147      "first_seen": "2026-02-17"148    }149  ],150  "last_run": "2026-02-17"151}152~~~153154## Step 3: Research and Fix Broken Links155156For each broken link found in the test results (but NOT in the unfixable list):1571581. **Investigate the link:**159   - Determine what the link was supposed to point to based on:160     - The link text in the markdown161     - The context around the link162     - The surrounding documentation163   1642. **Search for alternatives:**165   - Use web-fetch to search for if the content has moved to a new URL166   - Try common alternatives (www vs non-www, http vs https, with/without trailing slash)167   - Look for redirects or updated documentation168   - Check if there's an official replacement169   1703. **Fix the link:**171   - If you find a working replacement URL, use the `edit` tool to update the markdown file172   - Replace the broken URL with the working one173   - Make sure to preserve the link text and formatting174   1754. **Document unfixable links:**176   - If a link truly cannot be fixed (content permanently removed, no alternatives found):177     - Add it to the unfixable_links list in cache memory178     - Include the URL, reason, and date179     - This prevents future runs from wasting time on the same broken link180181## Step 4: Update Cache Memory182183After processing all broken links:184- Update the cache memory with any new unfixable links185- Update the "last_run" timestamp186- Save the updated cache memory187188## Step 5: Create Pull Request or Noop189190Based on your work:191192**If you fixed any links:**193- Use the `create-pull-request` safe output to create a PR with your fixes194- In the PR body, include:195  - A summary of how many links were fixed196  - A list of the broken links and their replacements197  - Any links that were added to the unfixable list198- Title format: "Fix broken documentation links"199200**If no links needed fixing:**201- Use the `noop` safe output with a clear message like:202  - "All documentation links are working correctly" (if no broken links found)203  - "All broken links are in the unfixable list, no new fixes available" (if broken links exist but can't be fixed)204205## Important Guidelines206207- **Be thorough:** Check every broken link carefully208- **Preserve context:** When replacing links, make sure the new URL points to equivalent or better content209- **Document everything:** Keep the cache memory up to date with unfixable links210- **Be selective:** Only add links to the unfixable list if you've genuinely tried to find alternatives211- **Use web-fetch wisely:** Try to fetch the broken URL and check for redirects or alternatives212- **Relative links:** Focus only on HTTP(S) links. Skip relative links and anchors (they're tested differently)213214## Example Cache Memory Update215216~~~json217{218  "unfixable_links": [219    {220      "url": "https://old-docs.example.com/api/v1",221      "reason": "Documentation site shut down, no replacement found despite searching",222      "first_seen": "2026-02-17"223    }224  ],225  "last_run": "2026-02-17"226}227~~~228229## Context230231- Repository: `${{ github.repository }}`232- Run daily on weekdays to catch broken links early233- Link test results are available at `/tmp/gh-aw/agent/link-check-results.md`